Skip to content

Commit 95df8a5

Browse files
feat: expose Altimate Base registration over HTTP for non-TUI hosts (#1266)
Co-authored-by: Claude Opus 5 (1M context) <[email protected]>
1 parent 1bbf453 commit 95df8a5

15 files changed

Lines changed: 759 additions & 21 deletions
Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
// altimate_change start — the single definition of the Altimate Base consent disclosure.
2+
//
3+
// This text is what a user actually consents against before any Base credential is minted, so it
4+
// must be identical everywhere it is shown. Two packages render it and neither can import from the
5+
// other: the TUI's disclosure dialog (`packages/tui`) and the HTTP disclosure route that serves
6+
// hosts rendering their own dialog (`packages/opencode`, for the VS Code extension's chat panel).
7+
// `packages/core` is the only module both already depend on, so the constant lives here.
8+
//
9+
// A new leaf file rather than an addition to an existing core module, so it adds no upstream
10+
// rebase surface.
11+
//
12+
// It states the core data terms up front. The persistent per-install-id linkage detail is
13+
// disclosed in docs/docs/configure/providers.md ("Data handling") rather than repeated in the
14+
// gate (see #1268); keep the core terms in sync with that note.
15+
export const ALTIMATE_BASE_DISCLOSURE =
16+
"Altimate Base is free and requires no signup. Requests and responses may be logged and used to improve Altimate's products, including the model. Secrets are automatically masked before storage, but don't rely on it — avoid sending secrets or confidential code. Usage can be rate limited."
17+
18+
/**
19+
* The one-line subtitle shown next to Altimate Base in a provider or model picker. Shared for the
20+
* same reason as the disclosure: it previously existed in three drifting variants across the TUI
21+
* pickers and the extension.
22+
*/
23+
export const ALTIMATE_BASE_HINT = "free · no signup · rate limited"
24+
// altimate_change end

‎packages/opencode/src/altimate/free/capability.ts‎

Lines changed: 13 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -66,9 +66,19 @@ let redeemerIssued = false
6666

6767
/**
6868
* Hands out the ability to arm Altimate Base's production consent authority. Callable exactly
69-
* once per process: a second call throws. The sole legitimate caller is the registration consent
70-
* gate built once at TUI worker boot (`cli/tui/worker.ts`), before any plugin, tool, or session
71-
* code has a chance to run. Because this is the only way to arm the authority that
69+
* once per process: a second call throws.
70+
*
71+
* THIS DOCSTRING IS THE CANONICAL DESCRIPTION of who may claim it. `client.ts` and the entrypoints
72+
* point here rather than restating it — the claim was previously paraphrased in three files and went
73+
* stale in two of them when a second entrypoint was added.
74+
*
75+
* Legitimate callers, one per process, each owning a surface that shows a disclosure:
76+
* - `cli/tui/worker.ts` — the terminal consent dialog
77+
* - `cli/cmd/serve.ts` — the consent-gated HTTP routes the VS Code extension drives
78+
* `test/altimate/altimate-base-armer-callsites.test.ts` asserts that list against the source, so
79+
* adding a claimer fails there and forces this comment to be revisited.
80+
*
81+
* Because this is the only way to arm the authority that
7282
* `registerAfterConsent` checks against, no other in-process code — however it constructs its
7383
* own `ConsentCapabilityStore` or calls this function again — can mint a token that will ever be
7484
* accepted; a self-armed store only ever validates against itself.

‎packages/opencode/src/altimate/free/client.ts‎

Lines changed: 10 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -345,9 +345,16 @@ async function registerOnce(
345345
* by the discipline of its callers. A caller cannot forge a token by constructing their own
346346
* `ConsentCapabilityStore`: that class's `arm`/`consume` only ever validate against the instance
347347
* you built, and the ONE instance this function actually checks is never exported — the only way
348-
* to arm it is `FreeTierCapability.issueArmer()`, claimed once by the TUI worker's consent gate at
349-
* boot. A future CLI, HTTP route, or plugin cannot register by importing this: it would have to
350-
* obtain a token minted by that gate. Provider discovery and inference never call it.
348+
* to arm it is `FreeTierCapability.issueArmer()`, which is claimable exactly once per process. See
349+
* that function's docstring for which entrypoints may claim it — deliberately not repeated here.
350+
*
351+
* So importing this function is not enough to register: a caller must obtain a token minted by
352+
* whichever gate claimed the armer in its process. Provider discovery and inference never call it.
353+
*
354+
* What this guarantees: the token is authentic. What it does not: that a human read anything. Over
355+
* HTTP that remains an assertion by the caller, narrowed only by the disclosure-hash check in
356+
* `FreeTierHost.registerWithAcceptedDisclosure` — and that hash is derived from public text, so it
357+
* proves the caller holds the current wording, not that anyone read it.
351358
*/
352359
export async function registerAfterConsent(
353360
token: string,

‎packages/opencode/src/altimate/free/consent.ts‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,36 @@
1+
import { createHash } from "node:crypto"
2+
import { ALTIMATE_BASE_DISCLOSURE } from "@opencode-ai/core/altimate-base-disclosure"
13
import { FreeTier } from "./client"
24
import { FreeTierStore } from "./store"
35

6+
/**
7+
* The text a user consents against before any Base credential is minted, plus the picker hint,
8+
* served to hosts that render their own disclosure (the VS Code extension's chat panel, via
9+
* GET /altimate/base/disclosure).
10+
*
11+
* Both are defined once in `@opencode-ai/core/altimate-base-disclosure` and re-exported here, so
12+
* the TUI dialog and this route can never drift apart.
13+
*/
14+
export {
15+
ALTIMATE_BASE_DISCLOSURE as DISCLOSURE,
16+
ALTIMATE_BASE_HINT as HINT,
17+
} from "@opencode-ai/core/altimate-base-disclosure"
18+
19+
/**
20+
* SHA-256 of the canonical disclosure, hex-encoded.
21+
*
22+
* `POST /altimate/base/register` requires the caller to echo this back. This is a **text-version
23+
* agreement, not proof of consent**: it establishes that the caller holds the current disclosure,
24+
* so a client still rendering superseded wording cannot register people against text they were
25+
* never shown. It does NOT establish that a human read anything — any caller can GET the disclosure
26+
* and echo the hash. Whether a person actually saw the text remains an assertion by the caller.
27+
*
28+
* Not a secret (it is derived from public text), so a plain comparison is fine.
29+
*/
30+
export function disclosureHash(): string {
31+
return createHash("sha256").update(ALTIMATE_BASE_DISCLOSURE, "utf8").digest("hex")
32+
}
33+
434
export type RegistrationResult =
535
| { ok: true }
636
| {
Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
// altimate_change start — host-injected Altimate Base registration for non-TUI entrypoints.
2+
//
3+
// `FreeTierCapability.issueArmer()` is claimable exactly once per process and throws on a second
4+
// call, so an HTTP route cannot claim one for itself: the TUI worker already claims it at boot for
5+
// its own RPC gate, and that worker also serves HTTP from the same process. A route-level claim
6+
// would therefore break the TUI worker the moment the routes module loaded — and any test that
7+
// imported both the server and the Base test harness.
8+
//
9+
// Instead the entrypoint that owns the process claims the capability once and hands the resulting
10+
// gate here. This is the same shape the TUI already uses for the same operation
11+
// (`packages/tui/src/context/altimate-base-consent.tsx`): the host injects, the consumer checks.
12+
//
13+
// `altimate serve` provides a gate. The TUI worker deliberately does NOT — the TUI owns its own
14+
// disclosure dialog, and a second registration surface inside that process would let a caller
15+
// register without the dialog ever being shown. Consumers must treat "cannot register" as final
16+
// and refuse, exactly as the TUI's provider picker does.
17+
//
18+
// The gate itself is NEVER handed back out. An earlier revision exposed `current()`, which returned
19+
// the whole gate — including `setToken` (closing over the real armer) and `register` (redeeming
20+
// against the real authority) — so any importer held a raw mint primitive and could register
21+
// without going near the disclosure, in any order it liked. The check now happens *inside* this
22+
// module, in the same call that mints, arms and redeems: there is no ordering for a caller to get
23+
// wrong and no primitive to borrow.
24+
//
25+
// What this is NOT: a trust boundary against in-process code. `registerWithAcceptedDisclosure` is
26+
// exported, and the hash it demands is a SHA-256 of public text that any caller can recompute via
27+
// `FreeTierConsent.disclosureHash()`. In-process code can therefore still cause a registration —
28+
// it simply cannot do so while bypassing the documented precondition, and there is now one
29+
// audited path instead of a capability handed to every importer. The real boundary is the process:
30+
// anything running here is already trusted to execute tools. What this closes is accidental
31+
// misuse and the drift that comes from re-implementing the check at each call site.
32+
import { randomBytes } from "node:crypto"
33+
import type { createRegistrationConsentGate, RegistrationResult } from "./consent"
34+
import { FreeTierConsent } from "./consent"
35+
36+
export type Registration = ReturnType<typeof createRegistrationConsentGate>
37+
38+
let registration: Registration | undefined
39+
40+
/**
41+
* Install the process's registration gate. Called once by the entrypoint, before the server starts
42+
* accepting requests.
43+
*
44+
* Single-shot, matching every other capability in this area: a second call throws rather than
45+
* silently replacing the gate. The earlier last-write-wins behaviour let any in-process caller swap
46+
* the gate out from under the routes after `serve` installed the real one. That was never a
47+
* privilege escalation — such code is already trusted and still cannot forge a token the private
48+
* authority accepts — but it was a weaker invariant than `issueArmer()`/`issueRedeemer()` next door,
49+
* for no benefit.
50+
*/
51+
export function provide(value: Registration): void {
52+
if (registration) throw new Error("Altimate Base registration gate already provided for this process")
53+
registration = value
54+
}
55+
56+
/** Whether this host can register Altimate Base at all, i.e. whether an entrypoint provided a gate. */
57+
export function canRegister(): boolean {
58+
return registration !== undefined
59+
}
60+
61+
export type RegisterOutcome =
62+
/** No gate was provided; this host cannot register Altimate Base. */
63+
| { kind: "unavailable" }
64+
/** The caller echoed a hash that is not the current disclosure's. */
65+
| { kind: "staleDisclosure" }
66+
/** The gate ran; `result` carries its success or its classified failure. */
67+
| { kind: "done"; result: RegistrationResult }
68+
69+
/**
70+
* Verify the caller accepted the current disclosure text, then mint, arm and redeem in one step.
71+
*
72+
* The hash comparison lives here rather than in the caller so that holding the current disclosure
73+
* text is a precondition of minting, not a convention the caller is trusted to follow. It is a
74+
* **text-version agreement, not proof of consent**: it establishes that the caller holds the
75+
* current wording, so a client still rendering superseded text cannot register people against text
76+
* they were never shown. Any caller can fetch the disclosure and echo the hash, so "a human read
77+
* this" remains an assertion by the caller.
78+
*/
79+
export async function registerWithAcceptedDisclosure(acceptedDisclosureSha256: string): Promise<RegisterOutcome> {
80+
const gate = registration
81+
if (!gate) return { kind: "unavailable" }
82+
if (acceptedDisclosureSha256.toLowerCase() !== FreeTierConsent.disclosureHash()) {
83+
return { kind: "staleDisclosure" }
84+
}
85+
const token = randomBytes(32).toString("hex")
86+
gate.setToken({ token })
87+
return { kind: "done", result: await gate.register({ token }) }
88+
}
89+
90+
export * as FreeTierHost from "./host"
91+
// altimate_change end

‎packages/opencode/src/cli/cmd/serve.ts‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,17 @@ import { subscribeTraceConsumer } from "../../altimate/observability/trace-consu
88
// altimate_change start — self-update on headless serve startup
99
import { scheduleStartupUpgradeCheck } from "./serve-upgrade-check"
1010
// altimate_change end
11+
// altimate_change start — Altimate Base registration capability for the headless server
12+
import { FreeTier } from "../../altimate/free/client"
13+
import { FreeTierCapability } from "../../altimate/free/capability"
14+
import { FreeTierConsent } from "../../altimate/free/consent"
15+
import { FreeTierHost } from "../../altimate/free/host"
16+
import { Log } from "../../util/log"
17+
// altimate_change end
18+
19+
// altimate_change start — logger for the Base registration gate's onUnexpectedError hook
20+
const log = Log.create({ service: "serve" })
21+
// altimate_change end
1122

1223
export const ServeCommand = effectCmd({
1324
command: "serve",
@@ -25,6 +36,21 @@ export const ServeCommand = effectCmd({
2536
// because it must be readable from every module realm.
2637
process.env["ALTIMATE_CODE_SERVE"] = "1"
2738
// altimate_change end
39+
// altimate_change start — claim the process's one Altimate Base consent capability here, at the
40+
// entrypoint, before the server can accept a request. `serve` is the extension's host and has no
41+
// TUI to show the disclosure dialog, so the disclosure + registration routes are how a Base
42+
// credential gets minted in this process. Claiming it here (rather than in the routes module)
43+
// keeps the TUI worker — which claims the same capability for its own dialog — unaffected.
44+
yield* Effect.sync(() =>
45+
FreeTierHost.provide(
46+
FreeTierConsent.createRegistrationConsentGate({
47+
arm: FreeTierCapability.issueArmer(),
48+
register: (token) => FreeTier.registerAfterConsent(token),
49+
onUnexpectedError: (error) => log.error("Altimate Base registration failed", { error }),
50+
}),
51+
),
52+
)
53+
// altimate_change end
2854
const { Server } = yield* Effect.promise(() => import("../../server/server"))
2955
if (!Flag.OPENCODE_SERVER_PASSWORD) {
3056
console.log("Warning: OPENCODE_SERVER_PASSWORD is not set; server is unsecured.")

‎packages/opencode/src/cli/tui/worker.ts‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -91,8 +91,9 @@ GlobalBus.on("event", (event) => {
9191

9292
let server: Awaited<ReturnType<typeof Server.listen>> | undefined
9393
// altimate_change start — worker-local, expiring capabilities gate every registration mutation.
94-
// `issueArmer()` can succeed exactly once per process; this is that one legitimate call — see
95-
// capability.ts for why that makes the resulting token unforgeable by any other in-process code.
94+
// `issueArmer()` can succeed exactly once per process; this is this process's claim — see
95+
// capability.ts for the canonical list of entrypoints that may claim it, and for why that makes the
96+
// resulting token unforgeable by any other in-process code.
9697
const altimateBaseRegistration = FreeTierConsent.createRegistrationConsentGate({
9798
arm: FreeTierCapability.issueArmer(),
9899
register: (token) => FreeTier.registerAfterConsent(token),

0 commit comments

Comments
 (0)