Skip to content

Restore /sk-activate command (GitHub device flow + license JWT) - #36

Merged
minarc merged 1 commit into
mainfrom
feat/restore-sk-activate-command
Apr 21, 2026
Merged

minarc merged 1 commit into
mainfrom
feat/restore-sk-activate-command

Conversation

@minarc

@minarc minarc commented Apr 21, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Follow-up to #35. The emergency routing override keeps telemetry flowing without a license, but it also removed the `/sk-activate` path so users can no longer register their device or obtain a license JWT. This PR restores that path, mirroring the VS Code extension's `AuthService` flow.

Flow (mirrors the VS Code extension)

  1. Silent `gh auth token` path — if the GitHub CLI is already authenticated, POST the token + `device_id` to `https://api.meter.skillbench.com/activate\` and store the returned license JWT. Failures/cooldowns are cached in the credstore so hooks don't hammer the endpoint.
  2. GitHub OAuth device flow fallback — print a URL + user code, poll the token endpoint until the user approves, then exchange for a license JWT.

Uses the same OAuth app as the VS Code extension: `client_id=Ov23ct86rS80kpl7o2Xg`, `scope=read:user read:org`.

Files

  • `skillmeter/commands/sk-activate.md` — slash command definition
  • `skillmeter/scripts/activate.js` — device flow + license exchange entrypoint
  • `skillmeter/scripts/credstore.js` — adds `trySilentGhActivate`, `get/setGhFallbackRetryAfter`, `ACTIVATE_URL` (all exported)

Relation to #35

  • Telemetry still flows without activation — PR Emergency telemetry routing override (device_id only gate) #35's device_id-only gate is unchanged.
  • Activation is explicit and user-initiated via `/sk-activate`. Running it registers the device in the tenant system and gives the plugin a signed JWT; the telemetry hot path does not depend on it.

Test plan

  • `node -c activate.js` / `credstore.js` — syntax clean
  • Run `/sk-activate` with `gh` already logged in → activation succeeds via silent path
  • Run `/sk-activate` without `gh` → device flow prints URL+code, completes after browser approval
  • After activation, `~/.skillbench/credentials.json` contains `license_jwt`
  • Second `/sk-activate` run reports "already activated"

🤖 Generated with Claude Code

Summary by CodeRabbit

Release Notes

  • New Features
    • Added GitHub sign-in activation for SkillMeter. Users can now activate using their GitHub account with automatic silent activation when credentials are available, or through an interactive GitHub authorization flow.

Mirrors the VS Code extension's AuthService flow:
  1. `gh auth token` silent path — if the user already has the GitHub
     CLI authenticated, POST the token + device_id to
     https://api.meter.skillbench.com/activate and store the returned
     license JWT. Failures are cached in the credstore so repeated
     hooks don't hammer the endpoint.
  2. GitHub OAuth device flow fallback — print a URL + user code,
     poll the token endpoint until the user approves, then exchange
     for a license JWT.

Activation is explicit and user-initiated (via /sk-activate). It
registers the device in the tenant system and obtains a signed JWT
whose `telemetry_endpoint` and claims are used by downstream
services. Telemetry itself already works without a license (PR #35);
this PR restores the path for users who want to be fully activated.

- skillmeter/commands/sk-activate.md: slash command definition
- skillmeter/scripts/activate.js: device flow + license exchange
- skillmeter/scripts/credstore.js: trySilentGhActivate +
  get/setGhFallbackRetryAfter + ACTIVATE_URL, exported for reuse

Uses the same GitHub OAuth client_id as the VS Code extension
(Ov23ct86rS80kpl7o2Xg) and the same scopes (read:user read:org).
The activation URL is the prod API Gateway custom domain
(api.meter.skillbench.com/activate).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@coderabbitai

coderabbitai Bot commented Apr 21, 2026 •

Copy link
Copy Markdown
Contributor
🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 10.00% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title clearly and accurately summarizes the main changes: restoring the /sk-activate command with GitHub device flow and license JWT functionality, which is the primary objective of the PR.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch feat/restore-sk-activate-command

Comment @coderabbitai help to get the list of available commands and usage tips.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick comments (4)
skillmeter/scripts/credstore.js (2)

193-206: Consider logging when gh auth token fails for debuggability.

Currently, failures are silently swallowed and the cooldown is set. Adding a debug log (to stderr or a log file) would help users diagnose why silent activation failed—especially distinguishing "gh not installed" from "gh not authenticated."

Example enhancement
   try {
     ghToken = execSync("gh auth token", {
       encoding: "utf8",
       stdio: ["pipe", "pipe", "ignore"],
       timeout: 3000,
     }).trim();
-  } catch {
+  } catch (err) {
+    // Optionally log: console.error("[skillmeter] gh auth token failed:", err.message);
     setGhFallbackRetryAfter(now + FAILURE_COOLDOWN);
     return null;
   }
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@skillmeter/scripts/credstore.js` around lines 193 - 206, When the execSync
call to run "gh auth token" fails (or returns an empty token) the code currently
swallows the error and only calls setGhFallbackRetryAfter; update the catch
block and the subsequent !ghToken branch to emit a debug/error log including the
caught error or a clear message distinguishing "gh not installed" vs "gh not
authenticated" so failures are diagnosable—use the same logger used elsewhere
(or console.error/stderr) and include context like the command string, the
error.message/stack, and the retry timestamp; refer to the execSync("gh auth
token") call and the setGhFallbackRetryAfter(now + FAILURE_COOLDOWN) usage to
locate where to add the logs.

188-249: Potential race condition with concurrent activations.

trySilentGhActivate performs multiple read-modify-write operations on the credential store without file locking. If two activate.js instances run concurrently (e.g., user rapidly invokes /sk-activate twice), both could pass the cooldown check, both succeed with different license tokens, and race to write state—potentially leaving stale data.

Given activation is user-initiated and presumably rare, this is low risk in practice. However, consider adding an advisory file lock around the credential store writes, or at minimum document this limitation.

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@skillmeter/scripts/credstore.js` around lines 188 - 249, trySilentGhActivate
has a race where multiple processes can pass the cooldown checks and
concurrently read/modify the credential store via getGhFallbackRetryAfter,
setGhFallbackRetryAfter and setLicenseToken; wrap the critical read-modify-write
section in an advisory file lock (or use an existing lock library) around the
credential store before doing the cooldown check and before writing the new
state so only one process can update at a time, then release the lock;
specifically acquire the lock at the start of trySilentGhActivate (or
immediately before reading getGhFallbackRetryAfter) and hold it until after
setLicenseToken and setGhFallbackRetryAfter(0) (or, if you prefer a smaller
scope, lock only around the sequence that re-checks cooldown, posts to
ACTIVATE_URL and writes the resulting jwt), and fall back to documented
limitation if locking is unavailable.
skillmeter/scripts/activate.js (2)

41-45: postForm throws on non-OK but then calls res.json() unconditionally after.

If the response is not OK, the function throws before reaching res.json(). However, if the server returns a 200 OK with invalid JSON, this will throw an unhandled JSON parse error. Consider wrapping the JSON parse or adding a catch.

Defensive JSON parsing
-  return res.json();
+  try {
+    return await res.json();
+  } catch {
+    throw new Error(`${url} returned invalid JSON`);
+  }
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@skillmeter/scripts/activate.js` around lines 41 - 45, The postForm function
currently throws for non-OK responses but then calls res.json() unguarded, which
allows a JSON parse error to bubble up on a 200 with invalid JSON; update
postForm to defensively parse JSON: after the OK check, attempt to parse
response body inside a try/catch (or read as text then JSON.parse inside try)
and on parse failure throw a new Error that includes the URL, status, and the
raw response text so callers get a clear, handled error; locate the parsing call
in postForm (the return res.json() line) and replace it with the guarded parsing
logic.

30-46: Error handling in postForm could leak sensitive information.

The error message includes the full response text, which might contain sensitive details from the server. For OAuth endpoints this is typically fine, but consider truncating very long responses.

Optional: truncate error text
   if (!res.ok) {
-    const text = await res.text().catch(() => "");
-    throw new Error(`${url} returned ${res.status}: ${text}`);
+    const text = await res.text().catch(() => "");
+    const truncated = text.length > 200 ? text.slice(0, 200) + "..." : text;
+    throw new Error(`${url} returned ${res.status}: ${truncated}`);
   }
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@skillmeter/scripts/activate.js` around lines 30 - 46, The postForm function
currently throws an error that embeds the entire response text which may contain
sensitive or very large content; modify postForm (the async function postForm)
to read the response text but sanitize/truncate it before including in the
thrown Error (for example limit to a safe length like 200 characters and append
"… (truncated)" when longer), and ensure you still handle failures to read the
body (use the existing .catch fallback to empty string) so the thrown message
includes only the truncated/sanitized snippet plus the status and URL.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@skillmeter/scripts/activate.js`:
- Around line 41-45: The postForm function currently throws for non-OK responses
but then calls res.json() unguarded, which allows a JSON parse error to bubble
up on a 200 with invalid JSON; update postForm to defensively parse JSON: after
the OK check, attempt to parse response body inside a try/catch (or read as text
then JSON.parse inside try) and on parse failure throw a new Error that includes
the URL, status, and the raw response text so callers get a clear, handled
error; locate the parsing call in postForm (the return res.json() line) and
replace it with the guarded parsing logic.
- Around line 30-46: The postForm function currently throws an error that embeds
the entire response text which may contain sensitive or very large content;
modify postForm (the async function postForm) to read the response text but
sanitize/truncate it before including in the thrown Error (for example limit to
a safe length like 200 characters and append "… (truncated)" when longer), and
ensure you still handle failures to read the body (use the existing .catch
fallback to empty string) so the thrown message includes only the
truncated/sanitized snippet plus the status and URL.

In `@skillmeter/scripts/credstore.js`:
- Around line 193-206: When the execSync call to run "gh auth token" fails (or
returns an empty token) the code currently swallows the error and only calls
setGhFallbackRetryAfter; update the catch block and the subsequent !ghToken
branch to emit a debug/error log including the caught error or a clear message
distinguishing "gh not installed" vs "gh not authenticated" so failures are
diagnosable—use the same logger used elsewhere (or console.error/stderr) and
include context like the command string, the error.message/stack, and the retry
timestamp; refer to the execSync("gh auth token") call and the
setGhFallbackRetryAfter(now + FAILURE_COOLDOWN) usage to locate where to add the
logs.
- Around line 188-249: trySilentGhActivate has a race where multiple processes
can pass the cooldown checks and concurrently read/modify the credential store
via getGhFallbackRetryAfter, setGhFallbackRetryAfter and setLicenseToken; wrap
the critical read-modify-write section in an advisory file lock (or use an
existing lock library) around the credential store before doing the cooldown
check and before writing the new state so only one process can update at a time,
then release the lock; specifically acquire the lock at the start of
trySilentGhActivate (or immediately before reading getGhFallbackRetryAfter) and
hold it until after setLicenseToken and setGhFallbackRetryAfter(0) (or, if you
prefer a smaller scope, lock only around the sequence that re-checks cooldown,
posts to ACTIVATE_URL and writes the resulting jwt), and fall back to documented
limitation if locking is unavailable.

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: f5527938-e7ae-4fa1-9934-f63e36a318f3

📥 Commits

Reviewing files that changed from the base of the PR and between 3b54fa4 and 23c10ad.

📒 Files selected for processing (3)
  • skillmeter/commands/sk-activate.md
  • skillmeter/scripts/activate.js
  • skillmeter/scripts/credstore.js

@minarc
minarc merged commit b8fc9e6 into main Apr 21, 2026
1 check passed
minarc added a commit that referenced this pull request Sep 15, 2026
`/skillmeter:signin` ran an RFC 8628 device flow against GitHub and
handed the resulting access token to /activate, which resolved a tenant
through a GitHub App installation. Nobody who onboarded normally has one
of those, so that route cannot see them at all (INF-112). The server
learned a second way to identify somebody in
skillmeter-license-activation#36; this is the client half.

The protocol does not change. The grant type string, the polling loop,
the slow_down backoff, the user-code box, the clipboard copy and the
detached background poll are all untouched, because they were already
the spec rather than anything GitHub-specific. What changes is the two
URLs, the client id, the scope, and which token comes back.

THE ID TOKEN, NOT THE ACCESS TOKEN. The broker's access tokens are
opaque: no claims, resolvable only through an admin endpoint /activate
has no route to. The id token is a signed JWT it verifies against the
public JWKS. `openid` in the scope is what makes the broker issue one,
and a response carrying an access token but no id token now fails
loudly rather than sending something the server will reject.

POLLING HAD TO LEARN THAT "PENDING" IS AN ERROR RESPONSE. This is the
part that would have broken in the field. OAuth error responses carry
HTTP 400 (RFC 6749 §5.2), and GitHub was the odd one out in answering
200 with the error in the body — so the old loop treated every non-2xx
as fatal. Measured against dev, the broker returns

  HTTP 400 {"error":"authorization_pending", ...}

which means the unmodified loop would have aborted on the first poll,
five seconds in, every single time, before anyone could approve. A body
that parses as JSON is now data whatever the status says; only an
unreadable response is a transport failure.

THE `gh auth token` SHORTCUT IS GONE, and removing it fixes a separate
bug. It called `licenseActivation.trySilentGhActivate` against a name
this file never required, so it threw ReferenceError. That is not new
and not dev-only: v0.33.0, v0.34.0 and v0.34.1 all carry the usage with
no import, so `/skillmeter:signin` has failed with "licenseActivation is
not defined" for every user without a current license in every released
version. No test covered main(), which is how it shipped three times.
(user_prompt_expansion_signin.js imports the same helper correctly and
is untouched here.)

The dev client id placeholder goes too. `__FILL_DEV_OAUTH_CLIENT_ID__`
was never filled in, so dev sign-in never worked either; the broker
client is registered under one id in every environment, so there is now
nothing to fill.

Verified against live dev infrastructure, not mocks:

  - `node --test`: 367 pass, 0 fail — identical to the baseline before
    this change.
  - Running signin.js with SKILLMETER_ENV=dev returns a real 8-character
    code from id.dev.skillbench.com, prints the prefilled
    verification_uri_complete, and spawns the background poll. The same
    command on origin/main dies with the ReferenceError above.
  - The two token-endpoint statuses above were read from dev by hand.

Not verified here: the leg that needs a browser — approval, consent, and
/activate returning a licence. That needs #36 deployed with
BROKER_ISSUER set (skillbench-infra#281), so this must not be released
before both have landed.

Refs INF-220, INF-112.

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
@TheStarkor
TheStarkor deleted the feat/restore-sk-activate-command branch September 21, 2026 18:40
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants