|
| 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 |
0 commit comments