A local-first multi-agent app development platform, built on PenguinHarness
/**
* Project-scoped ModelScope key authorization, through the harness's own bridge.
*
* ModelScope's OAuth cannot run inside the App: the code exchange needs a client secret the
* desktop App must not hold, and ModelScope returns that code to a redirect URI the App does
* not own. The bridge at `config.modelscopeBridgeUrl` keeps the secret and runs the exchange.
* The App speaks only the device-style start/poll pair below to the bridge, and receives
* exactly once an api-inference token delivery, which it then writes across the ModelScope
* group the same way any other group key is written.
*
* Two consequences of that single delivery shape most of this file. A poll that has already
* succeeded can never be re-polled — the bridge clears its server-side copy on delivery — so a
* write that fails afterwards keeps the token on the flow for `retryApply` instead of asking
* the user to authorize again. The refresh token is stored in web.db, never in
* .project_config.toml; model requests call `ensureFresh` before loading a runtime and again
* immediately before each upstream request, silently rotating the access token near expiry.
*/
import { randomBytes } from "node:crypto";
import { Interface, Module, Provide, Use } from "@adelie/core/kernel";
import { MODELSCOPE_PROVIDER_ID } from "@adelie/core/model-catalog";
import { HttpError } from "../http/errors.js";
import { normalizeModelScopeBridgeUrl } from "../config.js";
import { Config } from "../hmr/capabilities.js";
import type {
ModelProviderAuthToken,
ModelProviderAuthTokens,
ProjectConfigStore,
} from "../mechanisms/projects.js";
import type { ModelScopeAuthFlowStatusResponse } from "../api/types.js";
/** Recorded by the bridge alongside the flow; it identifies the App but does not gate it. */
export const MODELSCOPE_BRIDGE_CLIENT_ID = "penguin-harness";
const FLOW_TTL_MS = 10 * 60 * 1000;
const MAX_FLOWS_PER_OWNER = 8;
const MAX_RESPONSE_BYTES = 512 * 1024;
const REQUEST_TIMEOUT_MS = 10_000;
const MAX_ACCESS_TOKEN_LENGTH = 4096;
const MAX_REFRESH_TOKEN_LENGTH = 4096;
const MAX_AUTHORIZE_URL_LENGTH = 2048;
const DEFAULT_RETRY_AFTER_MS = 1_000;
const MAX_RETRY_AFTER_MS = 60_000;
const REFRESH_SKEW_MS = 5 * 60 * 1000;
const MAX_CONSECUTIVE_REFRESH_FAILURES = 3;
const REFRESH_FAILURE_BACKOFF_MS = 30_000;
type FlowStatus = "pending" | "applying" | "completed" | "cancelled" | "apply_failed" | "error";
interface Flow {
flowId: string;
projectId: string;
userId: string;
code: string | null;
deviceSecret: string | null;
authorizeUrl: string;
expiresAt: number;
status: FlowStatus;
error?: ModelScopeAuthFlowStatusResponse["error"];
applied?: number;
credential?: ModelScopeCredential;
polling?: Promise<void>;
retryPollAt?: number;
changed?: boolean;
}
export type ModelScopeAuthStatusResult = ModelScopeAuthFlowStatusResponse & { changed?: true };
export interface ModelScopeCredential {
accessToken: string;
refreshToken?: string;
expiresAt?: string;
}
export interface ModelScopeRefreshResult {
changed: boolean;
}
interface ModelScopeAuthDeps {
/** Base URL of the bridge, without a trailing slash (config.modelscopeBridgeUrl). */
bridgeUrl: string;
/** Writes the delivered credential; resolves to how many rows took the access token. */
applyCredential: (
projectId: string,
credential: ModelScopeCredential,
options?: { expectedRefreshToken?: string },
) => Promise<number>;
/** Reads the server-side refresh metadata for the group. */
readStoredCredential?: (projectId: string) => ModelProviderAuthToken | undefined;
fetchImpl?: typeof fetch;
now?: () => number;
}
function asRecord(value: unknown): Record<string, unknown> {
return value !== null && typeof value === "object" && !Array.isArray(value)
? (value as Record<string, unknown>)
: {};
}
async function readJsonBounded(response: Response): Promise<unknown> {
if (response.body === null) return null;
const reader = response.body.getReader();
const chunks: Uint8Array[] = [];
let size = 0;
try {
while (true) {
const part = await reader.read();
if (part.done) break;
size += part.value.byteLength;
if (size > MAX_RESPONSE_BYTES) {
await reader.cancel("Bridge response is too large.");
throw new Error("Bridge response is too large.");
}
chunks.push(part.value);
}
} finally {
reader.releaseLock();
}
const body = Buffer.concat(chunks).toString("utf8");
return body === "" ? null : JSON.parse(body);
}
function requiredString(value: unknown, maxLength: number, label: string): string {
if (typeof value !== "string" || value.length === 0 || value.length > maxLength) {
throw new Error(`The bridge returned an invalid ${label}.`);
}
return value;
}
/**
* The authorize URL is opened in a browser tab, so it is validated as an address rather than
* merely copied: the bridge generates it, and a value that is not an absolute http(s) URL with
* no embedded credentials has no business reaching `window.open`.
*/
function authorizeEndpoint(value: unknown): string {
const raw = requiredString(value, MAX_AUTHORIZE_URL_LENGTH, "authorize URL");
const parsed = new URL(raw);
if (
(parsed.protocol !== "http:" && parsed.protocol !== "https:") ||
parsed.username !== "" ||
parsed.password !== ""
) {
throw new Error("The bridge returned an invalid authorize URL.");
}
return raw;
}
function optionalTokenString(value: unknown, maxLength: number, label: string): string | undefined {
if (value === undefined || value === null || value === "") return undefined;
return requiredString(value, maxLength, label);
}
function optionalIsoDate(value: unknown, label: string): string | undefined {
if (value === undefined || value === null || value === "") return undefined;
const raw = requiredString(value, 128, label);
const ms = Date.parse(raw);
if (!Number.isFinite(ms)) throw new Error(`The bridge returned an invalid ${label}.`);
return new Date(ms).toISOString();
}
/** Validates the one-time delivery and extracts the api-inference credential. */
export function modelscopeCredential(
value: unknown,
fallbackRefreshToken?: string,
): ModelScopeCredential {
const body = asRecord(value);
if (body.status !== "completed") throw new Error("The bridge returned another status.");
return modelscopeToken(body.token, fallbackRefreshToken);
}
/** Validates POST /oauth/refresh, whose successful envelope is `{ token }` without flow status. */
export function modelscopeRefreshCredential(
value: unknown,
fallbackRefreshToken?: string,
): ModelScopeCredential {
return modelscopeToken(asRecord(value).token, fallbackRefreshToken);
}
function modelscopeToken(value: unknown, fallbackRefreshToken?: string): ModelScopeCredential {
const token = asRecord(value);
const refreshToken =
optionalTokenString(token.refreshToken, MAX_REFRESH_TOKEN_LENGTH, "refresh token") ??
fallbackRefreshToken;
const expiresAt = optionalIsoDate(token.expiresAt, "access token expiry");
return {
accessToken: requiredString(token.accessToken, MAX_ACCESS_TOKEN_LENGTH, "access token"),
...(refreshToken !== undefined ? { refreshToken } : {}),
...(expiresAt !== undefined ? { expiresAt } : {}),
};
}
/** Backward-compatible helper used by older tests and small validators. */
export function modelscopeAccessToken(value: unknown): string {
return modelscopeCredential(value).accessToken;
}
function retryAfterMs(value: unknown): number {
const seconds = asRecord(value).retryAfterSeconds;
if (typeof seconds !== "number" || !Number.isFinite(seconds) || seconds <= 0) {
return DEFAULT_RETRY_AFTER_MS;
}
return Math.min(MAX_RETRY_AFTER_MS, Math.ceil(seconds * 1000));
}
function retryAfterSeconds(value: unknown): number {
return Math.ceil(retryAfterMs(value) / 1000);
}
export class ModelScopeAuthService {
private readonly flows = new Map<string, Flow>();
private readonly refreshes = new Map<string, Promise<ModelScopeRefreshResult>>();
private readonly refreshFailures = new Map<
string,
{ refreshToken: string; count: number; retryAt: number }
>();
private readonly fetchImpl: typeof fetch;
private readonly now: () => number;
constructor(private readonly deps: ModelScopeAuthDeps) {
this.fetchImpl = deps.fetchImpl ?? ((...args) => fetch(...args));
this.now = deps.now ?? (() => Date.now());
}
private url(path: string): string {
return `${this.deps.bridgeUrl}${path}`;
}
private isPending(flow: Flow): boolean {
return (
this.flows.get(flow.flowId) === flow &&
flow.status === "pending" &&
flow.expiresAt > this.now()
);
}
private async request(path: string, init: RequestInit): Promise<Response> {
return this.fetchImpl(this.url(path), {
...init,
redirect: "manual",
signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
});
}
async ensureFresh(input: {
projectId: string;
provider: string;
}): Promise<ModelScopeRefreshResult> {
if (input.provider !== MODELSCOPE_PROVIDER_ID) return { changed: false };
const stored = this.deps.readStoredCredential?.(input.projectId);
const state = this.refreshState(stored);
if (stored === undefined || state === "fresh") return { changed: false };
const key = `${input.projectId}:${input.provider}`;
const recordedFailures = this.refreshFailures.get(key);
const failures =
recordedFailures?.refreshToken === stored.refreshToken ? recordedFailures : undefined;
if (recordedFailures !== undefined && failures === undefined) {
this.refreshFailures.delete(key);
}
if (failures !== undefined) {
if (failures.count >= MAX_CONSECUTIVE_REFRESH_FAILURES) {
throw this.reauthorizationRequired();
}
if (state === "refresh" && failures.retryAt > this.now()) return { changed: false };
}
const existing = this.refreshes.get(key);
if (existing) return existing;
const refresh = this.refreshNow(input.projectId, input.provider, stored, state).finally(() => {
this.refreshes.delete(key);
});
this.refreshes.set(key, refresh);
return refresh;
}
async start(input: { projectId: string; userId: string }): Promise<{
flowId: string;
authorizeUrl: string;
expiresAt: string;
}> {
this.sweep();
const flowId = randomBytes(32).toString("base64url");
const code = randomBytes(32).toString("base64url");
const deviceSecret = randomBytes(32).toString("base64url");
let response: Response;
try {
response = await this.request("/oauth/start", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({
code,
deviceSecret,
client: { id: MODELSCOPE_BRIDGE_CLIENT_ID },
}),
});
} catch {
throw new HttpError(
502,
"modelscope_unreachable",
"The ModelScope bridge could not be reached.",
);
}
if (response.status === 429) {
let body: unknown = null;
try {
body = await readJsonBounded(response);
} catch {
// A malformed rate-limit response still gets the bounded default delay.
}
const retryAfter = retryAfterSeconds(body);
throw new HttpError(
429,
"modelscope_rate_limited",
"The ModelScope bridge is receiving too many authorization requests. Try again shortly.",
retryAfter,
);
}
if (response.status !== 201) {
throw new HttpError(
502,
"modelscope_start_failed",
"The ModelScope bridge refused the key flow.",
);
}
let body: Record<string, unknown>;
let authorizeUrl: string;
try {
body = asRecord(await readJsonBounded(response));
authorizeUrl = authorizeEndpoint(body.authorizeUrl);
} catch {
throw new HttpError(
502,
"modelscope_start_failed",
"The ModelScope bridge returned an invalid response.",
);
}
const expiresAt = typeof body.expiresAt === "string" ? Date.parse(body.expiresAt) : NaN;
if (!Number.isFinite(expiresAt) || expiresAt <= this.now()) {
throw new HttpError(
502,
"modelscope_start_failed",
"The ModelScope bridge returned an invalid expiry.",
);
}
this.evictOldest(input.userId, input.projectId);
// The bridge builds this URL itself (it is the one that knows the redirect URI and its own
// public prefix), so it is passed through rather than assembled here.
const localExpiresAt = Math.min(expiresAt, this.now() + FLOW_TTL_MS);
this.flows.set(flowId, {
flowId,
projectId: input.projectId,
userId: input.userId,
code,
deviceSecret,
authorizeUrl,
expiresAt: localExpiresAt,
status: "pending",
});
return { flowId, authorizeUrl, expiresAt: new Date(localExpiresAt).toISOString() };
}
async status(input: {
flowId: string;
projectId: string;
userId: string;
}): Promise<ModelScopeAuthStatusResult> {
const flow = this.requireFlow(input);
if (
flow.status === "pending" &&
(flow.retryPollAt === undefined || flow.retryPollAt <= this.now())
) {
flow.polling ??= this.pollBridge(flow).finally(() => {
flow.polling = undefined;
});
await flow.polling;
}
return this.publicFlow(flow);
}
async retryApply(input: {
flowId: string;
projectId: string;
userId: string;
}): Promise<ModelScopeAuthStatusResult> {
const flow = this.requireFlow(input);
if (flow.status !== "apply_failed" || flow.credential === undefined) {
throw new HttpError(
409,
"modelscope_auth_not_retryable",
"This key cannot be applied again.",
);
}
await this.apply(flow);
return this.publicFlow(flow);
}
cancel(input: { flowId: string; projectId: string; userId: string }): void {
const flow = this.requireFlow(input);
if (flow.status === "completed" || flow.status === "applying") {
throw new HttpError(
409,
"modelscope_auth_flow_used",
"This key flow can no longer be cancelled.",
);
}
flow.status = "cancelled";
// Best effort: the flow is cancelled locally whatever the bridge answers, and the code and
// secret are dropped either way so a later poll cannot revive it. The bridge also expires
// the flow on its own.
if (flow.code !== null && flow.deviceSecret !== null) {
const body = JSON.stringify({ code: flow.code, deviceSecret: flow.deviceSecret });
void this.request("/oauth/cancel", {
method: "POST",
headers: { "content-type": "application/json" },
body,
})
.then((response) => response.body?.cancel())
.catch(() => {});
}
flow.code = null;
flow.deviceSecret = null;
flow.credential = undefined;
}
private refreshState(
stored: ModelProviderAuthToken | undefined,
): "fresh" | "refresh" | "expired" {
if (stored === undefined || stored.accessTokenExpiresAt === undefined) return "fresh";
const expiresAt = Date.parse(stored.accessTokenExpiresAt);
if (!Number.isFinite(expiresAt)) return "fresh";
const now = this.now();
if (expiresAt <= now) return "expired";
return expiresAt <= now + REFRESH_SKEW_MS ? "refresh" : "fresh";
}
private async refreshNow(
projectId: string,
provider: string,
stored: ModelProviderAuthToken,
state: "refresh" | "expired",
): Promise<ModelScopeRefreshResult> {
const key = `${projectId}:${provider}`;
try {
const response = await this.request("/oauth/refresh", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ refreshToken: stored.refreshToken }),
});
if (!response.ok) throw new Error(`Bridge refresh failed: ${response.status}`);
const credential = modelscopeRefreshCredential(
await readJsonBounded(response),
stored.refreshToken,
);
const applied = await this.deps.applyCredential(projectId, credential, {
expectedRefreshToken: stored.refreshToken,
});
if (applied === 0) return { changed: false };
this.refreshFailures.delete(key);
return { changed: true };
} catch (error) {
const previous = this.refreshFailures.get(key);
const count = (previous?.refreshToken === stored.refreshToken ? previous.count : 0) + 1;
this.refreshFailures.set(key, {
refreshToken: stored.refreshToken,
count,
retryAt: this.now() + REFRESH_FAILURE_BACKOFF_MS * 2 ** (count - 1),
});
if (state === "refresh" && count < MAX_CONSECUTIVE_REFRESH_FAILURES) {
return { changed: false };
}
throw this.reauthorizationRequired();
}
}
private reauthorizationRequired(): HttpError {
return new HttpError(
409,
"modelscope_refresh_failed",
"ModelScope authorization could not be refreshed after repeated attempts. Authorize ModelScope again on the Models page.",
);
}
private async pollBridge(flow: Flow): Promise<void> {
if (!this.isPending(flow) || flow.code === null || flow.deviceSecret === null) return;
let response: Response;
try {
response = await this.request("/oauth/poll", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ code: flow.code, deviceSecret: flow.deviceSecret }),
});
} catch {
if (!this.isPending(flow)) return;
flow.status = "error";
flow.error = "unreachable";
return;
}
if (!this.isPending(flow)) return;
if (response.status === 429) {
let body: unknown = null;
try {
body = await readJsonBounded(response);
} catch {
// A malformed rate-limit response still gets a bounded default backoff.
}
if (!this.isPending(flow)) return;
flow.retryPollAt = this.now() + retryAfterMs(body);
return;
}
if (!response.ok) {
flow.status = "error";
flow.error = "upstream_failed";
return;
}
flow.retryPollAt = undefined;
let body: unknown;
try {
body = await readJsonBounded(response);
} catch {
if (!this.isPending(flow)) return;
flow.status = "error";
flow.error = "invalid_key";
return;
}
if (!this.isPending(flow)) return;
const status = asRecord(body).status;
if (status === "pending") return;
if (status === "completed") {
try {
flow.credential = modelscopeCredential(body);
} catch {
flow.status = "error";
flow.error = "invalid_key";
flow.code = null;
flow.deviceSecret = null;
return;
}
// The token is now in hand and the bridge's copy is gone: nothing may poll again.
flow.code = null;
flow.deviceSecret = null;
await this.apply(flow);
return;
}
flow.status = status === "cancelled" ? "cancelled" : "error";
flow.error =
status === "expired"
? "expired"
: status === "locked"
? "locked"
: status === "delivered"
? "already_delivered"
: status === "cancelled"
? undefined
: "upstream_failed";
flow.code = null;
flow.deviceSecret = null;
}
private async apply(flow: Flow): Promise<void> {
if (flow.credential === undefined) return;
flow.status = "applying";
flow.error = undefined;
try {
const applied = await this.deps.applyCredential(flow.projectId, flow.credential);
// A group with no rows would silently swallow the token, leaving the user authorized
// with nothing to show for it.
if (applied === 0) throw new Error("The ModelScope group is empty.");
this.refreshFailures.delete(`${flow.projectId}:${MODELSCOPE_PROVIDER_ID}`);
flow.applied = applied;
flow.credential = undefined;
flow.status = "completed";
flow.changed = true;
} catch {
// The token stays on the flow: the bridge cannot deliver it a second time, so the only
// way forward is retrying the write.
flow.status = "apply_failed";
flow.error = "apply_failed";
}
}
private publicFlow(flow: Flow): ModelScopeAuthStatusResult {
const changed = flow.changed === true;
flow.changed = false;
return {
status: flow.status,
...(flow.error !== undefined ? { error: flow.error } : {}),
...(flow.applied !== undefined ? { applied: flow.applied } : {}),
...(changed ? { changed: true as const } : {}),
};
}
private requireFlow(input: { flowId: string; projectId: string; userId: string }): Flow {
this.sweep();
const flow = this.flows.get(input.flowId);
if (
flow === undefined ||
flow.projectId !== input.projectId ||
flow.userId !== input.userId ||
flow.expiresAt <= this.now()
) {
throw new HttpError(
404,
"modelscope_auth_flow_not_found",
"This key flow has expired or does not exist.",
);
}
return flow;
}
private sweep(): void {
const now = this.now();
for (const [id, flow] of this.flows) if (flow.expiresAt <= now) this.flows.delete(id);
}
private evictOldest(userId: string, projectId: string): void {
const mine = [...this.flows.values()].filter(
(flow) => flow.userId === userId && flow.projectId === projectId,
);
for (const flow of mine.slice(0, Math.max(0, mine.length - (MAX_FLOWS_PER_OWNER - 1)))) {
this.flows.delete(flow.flowId);
}
}
}
/** The per-App ModelScope key authorization capability consumed by Project model routes. */
export abstract class ModelScopeAuth extends Interface<
Pick<ModelScopeAuthService, "start" | "status" | "retryApply" | "cancel" | "ensureFresh">
>() {}
/** Keep in-flight flows on the current bridge, like PlatformAuthProvider keeps them on Penguin Go. */
@Module()
export class ModelScopeAuthProvider {
@Use() private readonly config!: Config;
@Use() private readonly projectConfig!: ProjectConfigStore;
@Use() private readonly providerAuthTokens!: ModelProviderAuthTokens;
@Provide() auth!: ModelScopeAuth;
setup() {
this.auth = new ModelScopeAuthService({
// A runtime older than the field publishes none; the default is the production bridge.
bridgeUrl: this.config.modelscopeBridgeUrl ?? normalizeModelScopeBridgeUrl(undefined),
applyCredential: async (projectId, credential, options) => {
if (credential.refreshToken !== undefined) {
return this.projectConfig.setGroupApiKeyWithProviderAuthToken(
projectId,
MODELSCOPE_PROVIDER_ID,
credential.accessToken,
{
refreshToken: credential.refreshToken,
accessTokenExpiresAt: credential.expiresAt,
},
options,
);
}
return this.projectConfig.setGroupApiKey(
projectId,
MODELSCOPE_PROVIDER_ID,
credential.accessToken,
);
},
readStoredCredential: (projectId) =>
this.providerAuthTokens.get(projectId, MODELSCOPE_PROVIDER_ID),
});
}
}