Files
PaperClipAI/server/src/services/ephemeral-enrollment.ts
T
DottaandClaude Opus 5.5 12fc89b1f7 fix(cloud): let an online move proceed when Cloud supplies the database listener (#22263)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Hosted Paperclip servers can move from a server with a volume to a
volume-free server, which allows deploys without downtime
> - Before the move, Core checks that the volume-free configuration is
complete
> - That check requires `PAPERCLIP_DATABASE_LISTEN_URL` on the running
volume server, but only the volume-free replacement uses it, and Cloud
supplies it when it configures that replacement
> - Many older servers never had the setting, so they cannot move online
even when all their data is ready
> - This pull request stops an unset listener from blocking, and keeps a
listener that points at another database as a blocker
> - The benefit is that older servers can move online

## Linked Issues or Issue Description

**What existing behavior does this improve?**
The online move refuses a volume server that has no
`PAPERCLIP_DATABASE_LISTEN_URL`.

**Subsystem affected**
Server: ephemeral enrollment readiness
(`server/src/services/ephemeral-enrollment.ts`).

**Current behavior**
The eligibility read and preparation report
`volume_free_database_listener_required` for every server that has no
listener setting.

**Proposed behavior**
An unset listener does not block. A listener that does not match the
runtime database still blocks with the same name.

**Reason and benefit**
The replacement server receives the listener from Cloud. On staging,
this check alone blocks 18 servers whose data is otherwise ready.

**Breaking changes**
None. The startup contract for a running volume-free server is
unchanged.

## What Changed

- `services/ephemeral-enrollment.ts`: when the only configuration
failure is the listener, and the listener is unset, the readiness check
passes. The listener check is the last check in
`assertEphemeralServerConfig`, so all earlier settings were already
valid.
- `services/ephemeral-enrollment.test.ts`: tests for an unset listener
(eligible, and preparation succeeds) and a mismatched listener (still
blocked).

## Verification

- `npx vitest run src/services/ephemeral-enrollment.test.ts
src/routes/ephemeral-enrollment.test.ts`: 29/29 pass.

## Risks

- Low. Cloud's online arming passes `PAPERCLIP_DATABASE_LISTEN_URL` with
the replacement's variables. If the replacement did not get the setting,
the existing startup contract would still refuse to boot it, and the
move would not complete.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with tool use
(shell, file edits, browser).

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 20:39:56 -06:00

89 lines
5.3 KiB
TypeScript

import { createHash } from "node:crypto";
import { sql } from "drizzle-orm";
import { companySkillRepositorySnapshots, type Db } from "@paperclipai/db";
import { readBuildCommit } from "../build-commit.js";
import { loadConfig } from "../config.js";
import { conflict, unauthorized } from "../errors.js";
import { persistActivity, publishActivity } from "./activity-log.js";
import type { CloudControlClaims } from "./cloud-runtime-identity.js";
import { cloudTenantPrimaryCompanyId, getCloudStackContext } from "./cloud-instance.js";
import { resolveDecisionSigningSecret } from "./decision-signing.js";
import { assertEphemeralServerConfig, ephemeralServerEnabled, readEphemeralServerDataEligibility } from "./ephemeral-server-contract.js";
const configurationBlockers: Array<[RegExp, string]> = [
[/shared S3 storage, durable agent files and shared UI assets/, "volume_free_storage_flags_required"],
[/PAPERCLIP_SECRETS_MASTER_KEY/, "volume_free_master_key_required"],
[/PAPERCLIP_DECISION_SIGNING_SECRET|decision/i, "volume_free_decision_key_required"],
[/PAPERCLIP_DATABASE_LISTEN_URL/, "volume_free_database_listener_required"],
];
function volumeFreeConfigurationBlocker(): { blocker: string | null; decisionSigningSecret?: string } {
let decisionSigningSecret: string;
try {
decisionSigningSecret = resolveDecisionSigningSecret({ allowCreate: false });
} catch {
return { blocker: "volume_free_decision_key_required" };
}
try {
assertEphemeralServerConfig(loadConfig(), { ...process.env, PAPERCLIP_EPHEMERAL_SERVER: "true",
PAPERCLIP_DECISION_SIGNING_SECRET: decisionSigningSecret }, { allowMissingListener: true });
} catch (error) {
const message = error instanceof Error ? error.message : "";
return { blocker: configurationBlockers.find(([pattern]) => pattern.test(message))?.[1] ?? "volume_free_configuration_required" };
}
return { blocker: null, decisionSigningSecret };
}
async function onlineDataBlockers(db: Db) {
const { blockers } = await readEphemeralServerDataEligibility(db, { purpose: "startup" });
const [localPackage] = await db.select({ id: companySkillRepositorySnapshots.id }).from(companySkillRepositorySnapshots)
.where(sql`${companySkillRepositorySnapshots.storage}->>'provider' = 'local_disk'`).limit(1);
return localPackage && !blockers.includes("skills_require_migration") ? [...blockers, "skills_require_migration"] : blockers;
}
export async function readOnlineEphemeralEnrollmentEligibility(db: Db) {
const blockers = await onlineDataBlockers(db);
const eligible = blockers.length === 0;
const { blocker } = volumeFreeConfigurationBlocker();
return { eligible: eligible && !blocker, blockers: blocker ? [...blockers, blocker] : blockers, ephemeralServer: ephemeralServerEnabled() };
}
export async function prepareOnlineEphemeralEnrollment(db: Db, attemptId: string, control: Pick<CloudControlClaims, "requestId" | "exp">) {
const stackId = getCloudStackContext()?.stackId;
const commit = readBuildCommit();
const deploymentId = process.env.RAILWAY_DEPLOYMENT_ID;
if (!stackId || !commit || !deploymentId || !/^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/i.test(deploymentId)) {
throw conflict("Online enrollment requires a stamped managed Railway deployment");
}
const dataBlockers = await onlineDataBlockers(db);
if (dataBlockers.length) throw conflict("Durable data migration is incomplete", { blockers: dataBlockers });
const configuration = volumeFreeConfigurationBlocker();
if (configuration.blocker || !configuration.decisionSigningSecret) {
throw conflict("Volume-free configuration is incomplete", { blockers: [configuration.blocker ?? "volume_free_configuration_required"] });
}
const decisionSigningSecret = configuration.decisionSigningSecret;
const receipt = {
schema: "paperclip.online-ephemeral-enrollment.v1" as const,
attemptId, stackId, commit, deploymentId, observedAt: new Date().toISOString(),
ephemeralServer: ephemeralServerEnabled(),
decisionKeyDigest: createHash("sha256").update(decisionSigningSecret).digest("hex"),
enrollmentReady: false as const,
};
if (control.exp * 1000 <= Date.now()) throw unauthorized("Cloud preparation assertion expired");
const bytes = createHash("sha256").update(`paperclip-ephemeral-preparation:v1:${stackId}:${control.requestId}`).digest().subarray(0, 16);
bytes[6] = (bytes[6]! & 0x0f) | 0x50; bytes[8] = (bytes[8]! & 0x3f) | 0x80;
const hex = bytes.toString("hex");
const id = `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
try {
const { publication } = await persistActivity(db, { companyId: cloudTenantPrimaryCompanyId(stackId), actorType: "system", actorId: "paperclip-cloud",
action: "instance.ephemeral_enrollment.prepared", entityType: "instance", entityId: stackId, details: receipt }, { id });
publishActivity(publication);
} catch (error) {
const pg = (error as { cause?: { code?: string; constraint_name?: string } }).cause ?? error as { code?: string; constraint_name?: string };
if (pg.code === "23505" && pg.constraint_name === "activity_log_pkey") throw conflict("Cloud preparation assertion was already used");
throw error;
}
if (control.exp * 1000 <= Date.now()) throw unauthorized("Cloud preparation assertion expired");
return { ...receipt, decisionSigningSecret };
}