Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
4409c7a
fix(platform): name the rejected Cloudflare credential and list every…
Brooooooklyn Nov 20, 2026
eac24d8
fix(platform): report every denied plan read in one error
Brooooooklyn Nov 20, 2026
4d3bd56
docs(platform): explain which token to fix when AI Gateway is rejected
Brooooooklyn Nov 20, 2026
1702f07
fix(platform): wait through a stale deployment list after activation
Brooooooklyn Nov 20, 2026
38d0e02
fix(cli): name the platform R2 credentials when R2 rejects an upload …
Brooooooklyn Nov 20, 2026
e658065
fix(platform): require both R2 key pair values when replacing them
Brooooooklyn Nov 20, 2026
6e88460
feat(platform): add a signed R2 check for the platform's R2 key pair
Brooooooklyn Nov 20, 2026
738ee68
fix(platform): check the R2 key pair before repair or upgrade changes…
Brooooooklyn Nov 20, 2026
a56aa1b
docs(platform): explain R2 key pairs from the API and replacing them …
Brooooooklyn Nov 20, 2026
2e9f1e7
fix(platform): tell a clock problem and a malformed key ID apart in t…
Brooooooklyn Nov 20, 2026
639ad39
fix(platform): list each denied permission and request once
Brooooooklyn Nov 20, 2026
3d2eda1
fix(platform): keep the browser login name intact and offer a managem…
Brooooooklyn Nov 20, 2026
9ba9e43
fix(platform): name the credential on every Cloudflare denial and kee…
Brooooooklyn Nov 20, 2026
1b83648
fix(platform): name the management token from browser-login setup and…
Brooooooklyn Nov 20, 2026
2c825bf
fix(platform): skip a denial the plan's combined error already lists
Brooooooklyn Nov 20, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/guide/platform/installation/ci.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ Inject the following values from protected CI secrets. Do not commit them in a w
| `VOID_PLATFORM_HYPERDRIVE_ORIGIN_USER` | Hyperdrive runtime database user |
| `VOID_PLATFORM_HYPERDRIVE_ORIGIN_SERVICE_ID` | Workers VPC service ID, for a private database origin |
| `VOID_PLATFORM_R2_ACCESS_KEY_ID` | R2 Access Key ID |
| `VOID_PLATFORM_R2_SECRET_ACCESS_KEY` | R2 Secret Access Key |
| `VOID_PLATFORM_R2_SECRET_ACCESS_KEY` | R2 Secret Access Key (not the token value) |
| `VOID_PLATFORM_JWT_SECRET` | Original JWT signing secret |
| `VOID_PLATFORM_EMAIL_SIGNING_SECRET` | Dedicated email signing secret when email is enabled |
| `VOID_PLATFORM_PROJECT_SECRET_KEY` | Original base64-encoded project-encryption key |
Expand Down
2 changes: 2 additions & 0 deletions docs/guide/platform/installation/credentials.md
Original file line number Diff line number Diff line change
Expand Up @@ -113,6 +113,8 @@ The installer configures the email gateway and shared mail route. If setup fails

The installer opens the **R2 token creation** form with a token name based on your platform's display name, **Object Read & Write**, and **Apply to all buckets in this account (including newly created buckets)** preselected. Review the settings and create an account token, or a user token if your role requires it. Save its **Access Key ID** and **Secret Access Key** in your password manager, then paste both into the installer. These differ from the management and runtime API tokens. See [R2’s token instructions](https://developers.cloudflare.com/r2/api/tokens/).

If you create the token with the Cloudflare API instead, the Access Key ID is the token's ID and the Secret Access Key is the SHA-256 hex digest of the token value. Paste the Secret Access Key, not the token value.

## Signing and Encryption Keys {#signing-and-encryption-keys}

The **JWT signing key** signs platform login tokens. The **Project encryption key** encrypts app secrets stored by your platform. An interactive install generates both and keeps them in this machine's encrypted recovery data. Lifecycle commands on this machine read them from there.
Expand Down
10 changes: 8 additions & 2 deletions docs/guide/platform/installation/maintenance.md
Original file line number Diff line number Diff line change
Expand Up @@ -116,7 +116,9 @@ An upgrade validates the runtime, applies supported pending migrations, deploys

Install, upgrade, and repair also publish saved [AI Gateway logging](/reference/cli/platform-users#ai-gateway-logging) settings. Affected projects may show `pending` for about 2 minutes afterward, including projects returning to `inherit`. Check progress with `void platform project show <project-id>`.

Before starting, Void checks access to the installation's Cloudflare account, Workers, and existing R2 buckets. If credentials are rejected, set `CLOUDFLARE_API_TOKEN` to a management token scoped to that account and retry. This overrides the installation's saved management token.
Before starting, Void checks access to the installation's Cloudflare account, Workers, and existing R2 buckets. It lists every missing permission at once and names the credential Cloudflare rejected. If the management credential is rejected, set `CLOUDFLARE_API_TOKEN` to a management token scoped to that account and retry. This overrides the installation's saved management token.

With browser login, Void uses the runtime token for AI Gateway: `VOID_PLATFORM_RUNTIME_CLOUDFLARE_API_TOKEN`, or the one saved on this machine. If an error names the runtime token, set `VOID_PLATFORM_RUNTIME_CLOUDFLARE_API_TOKEN` to a valid runtime token, or set `CLOUDFLARE_API_TOKEN` to a management token with **Account → AI Gateway → Edit**. Void then uses that token instead of browser login.

Some upgrades pause application traffic until the new version passes health checks. If a command fails while traffic is paused:

Expand All @@ -127,12 +129,16 @@ Some upgrades pause application traffic until the new version passes health chec
::: details Migration safety, credential rotation, and rollback

To update the runtime Cloudflare token, GitHub OAuth credentials when GitHub login is enabled, or R2 credentials,
provide their `VOID_PLATFORM_*` environment variables when running the upgrade.
provide their `VOID_PLATFORM_*` environment variables when running `upgrade` or `repair`.
Only the supplied values replace live credentials. Recovery data from an older
workstation does not overwrite them, and upgrades preserve the live signing keys
and complete project-encryption keyring. Keep current credentials in your secret
manager so they can also restore a missing Worker during repair.

Set `VOID_PLATFORM_R2_ACCESS_KEY_ID` and `VOID_PLATFORM_R2_SECRET_ACCESS_KEY` together, even if
only the secret changed. Void checks the R2 pair against the assets bucket before it changes the
platform.

Database migrations only move forward. Void checks compatibility before upgrading and tells you if an intermediate release is needed. If deployment fails, it attempts to restore the previous Workers against the compatible database schema. Retrying does not repeat completed migrations.

After a successful upgrade, you can restore a declared-compatible earlier runtime without reversing migrations:
Expand Down
80 changes: 79 additions & 1 deletion packages/void/src/cli/direct-r2-upload.ts
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,80 @@ const MAX_R2_PUT_RETRIES = 3;
*/
const RETRY_BACKOFF_MS = [250, 500, 1000];

export const R2_CREDENTIALS_DOCS_URL =
'https://void.cloud/guide/platform/installation/credentials#r2-upload-credentials';

/**
* S3 error codes that mean R2 did not accept the signature on a presigned
* upload link. The platform signs every link with its own R2 key pair, so
* these usually point at that pair. Expiry and clock-skew codes are left out:
* they have other causes.
*/
export const R2_CREDENTIAL_ERROR_CODES: ReadonlySet<string> = new Set([
'Unauthorized',
'AccessDenied',
'SignatureDoesNotMatch',
'InvalidAccessKeyId',
]);

/**
* S3 error codes R2 answers with HTTP 400 when the Access Key ID is malformed,
* for example the token value pasted in place of the 32-character key ID.
*/
export const R2_MALFORMED_CREDENTIAL_ERROR_CODES: ReadonlySet<string> = new Set([
'InvalidArgument',
'AuthorizationHeaderMalformed',
]);

/** Whether an R2 error answer means R2 rejected the key pair itself. */
export function isR2CredentialRejection(status: number, code: string | undefined): boolean {
if (!code) {
return false;
}
if (status === 401 || status === 403) {
return R2_CREDENTIAL_ERROR_CODES.has(code);
}
return status === 400 && R2_MALFORMED_CREDENTIAL_ERROR_CODES.has(code);
}

/**
* Read the `<Code>` value from an S3-style XML error body. Returns
* `undefined` when the body has no complete, non-empty `<Code>` element.
*/
export function r2ErrorCode(body: string): string | undefined {
const open = '<Code>';
const start = body.indexOf(open);
if (start === -1) {
return undefined;
}
const valueStart = start + open.length;
const end = body.indexOf('</Code>', valueStart);
if (end === -1) {
return undefined;
}
const code = body.slice(valueStart, end).trim();
return code === '' ? undefined : code;
}

function directR2PutErrorMessage(
status: number,
hash: string,
path: string,
body: string,
code: string | undefined,
): string {
if (isR2CredentialRejection(status, code)) {
return (
`R2 rejected the upload signature (${code}) for ${path} (${hash}). ` +
"This usually means the platform's R2 upload credentials are wrong. " +
'Ask the platform operator to fix it. ' +
'If you run this platform: set VOID_PLATFORM_R2_ACCESS_KEY_ID and VOID_PLATFORM_R2_SECRET_ACCESS_KEY ' +
`to a working pair and run \`void platform repair\`. See ${R2_CREDENTIALS_DOCS_URL}`
);
}
return `R2 PUT failed for ${path} (${hash}): ${status}${body ? ` ${body}` : ''}`;
}

export class DirectR2PutError extends Error {
readonly status: number;
readonly hash: string;
Expand All @@ -30,14 +104,18 @@ export class DirectR2PutError extends Error {
* `BadDigest` (Content-MD5 mismatch) or signature errors.
*/
readonly body: string;
/** S3 `<Code>` parsed from `body`, when R2 returned an XML error. */
readonly code: string | undefined;

constructor(status: number, hash: string, path: string, body: string) {
super(`R2 PUT failed for ${path} (${hash}): ${status}${body ? ` ${body}` : ''}`);
const code = r2ErrorCode(body);
super(directR2PutErrorMessage(status, hash, path, body, code));
this.name = 'DirectR2PutError';
this.status = status;
this.hash = hash;
this.path = path;
this.body = body;
this.code = code;
}
}

Expand Down
9 changes: 7 additions & 2 deletions packages/void/src/cli/platform-auth-protection.ts
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,10 @@ import {
parsePlatformAccessSetupSpec,
preparePlatformAccessSetup,
} from './platform-access-setup.ts';
import { resolvePlatformCloudflareCredential } from './platform-auth.ts';
import {
platformOperatorCredentialLabel,
resolvePlatformCloudflareCredential,
} from './platform-auth.ts';
import { PlatformCloudflareClient } from './platform-cloudflare.ts';
import type { PlatformConfigArgs } from './platform-config-args.ts';
import { acquirePlatformDatabaseLifecycleLock } from './platform-installer.ts';
Expand Down Expand Up @@ -237,7 +240,9 @@ export async function runPlatformProtectionConfig(args: PlatformConfigArgs): Pro
);
}
const credential = await resolvePlatformCloudflareCredential();
const cloudflare = new PlatformCloudflareClient(credential.token);
const cloudflare = new PlatformCloudflareClient(credential.token, {
credential: platformOperatorCredentialLabel(credential),
});
let protection = null;
const checkpoint = { ...recovery };
const save = (values: Record<string, string>) => {
Expand Down
9 changes: 7 additions & 2 deletions packages/void/src/cli/platform-auth-recovery.ts
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,10 @@ import {
transaction,
type Connection,
} from './platform-auth-recovery-core.ts';
import { resolvePlatformCloudflareCredential } from './platform-auth.ts';
import {
platformOperatorCredentialLabel,
resolvePlatformCloudflareCredential,
} from './platform-auth.ts';
import { PlatformCloudflareClient } from './platform-cloudflare.ts';
import type { PlatformConfigArgs } from './platform-config-args.ts';
import {
Expand Down Expand Up @@ -85,7 +88,9 @@ export async function runPlatformAuthRecovery(args: PlatformConfigArgs): Promise
releaseDatabase.authoritativeManifest,
);
await verifyPlatformInstallationOwnership(
new PlatformCloudflareClient(credential.token),
new PlatformCloudflareClient(credential.token, {
credential: platformOperatorCredentialLabel(credential),
}),
manifest,
{ databaseUrl },
);
Expand Down
99 changes: 69 additions & 30 deletions packages/void/src/cli/platform-auth.ts
Original file line number Diff line number Diff line change
Expand Up @@ -4,11 +4,19 @@ import {
type CloudflareAccount,
type PlatformCloudflareClient,
} from './platform-cloudflare.ts';
import {
describePlatformCredential,
formatPlatformCredentialDenials,
type PlatformCredentialDenial,
type PlatformCredentialLabel,
} from './platform-credential-label.ts';
import { planCreatesZone, planWritesDns } from './platform-plan-writes.ts';
import type { PlatformInstallPlan } from './platform-plan.ts';

export type PlatformCloudflareCredential = Readonly<{
source: 'environment' | 'saved' | 'oauth';
/** Which variable held an `environment` token. */
environmentVariable?: 'CLOUDFLARE_API_TOKEN' | 'CF_API_TOKEN';
token: string;
}>;

Expand All @@ -24,76 +32,106 @@ export type PlatformManagementAccess = Readonly<{
readOnly: boolean;
}>;

/** The label of the operator credential, so Cloudflare errors can name it. */
export function platformOperatorCredentialLabel(
credential: Pick<PlatformCloudflareCredential, 'environmentVariable' | 'source'>,
): PlatformCredentialLabel {
return {
role: 'management',
source: credential.source,
...(credential.environmentVariable
? { environmentVariable: credential.environmentVariable }
: {}),
};
}

/** Use the selected credential for read-only checks before taking lifecycle locks. */
export async function verifyPlatformCloudflareCredential(
client: Pick<PlatformCloudflareClient, 'listAccounts' | 'listWorkerNames' | 'request'>,
input: {
account: CloudflareAccount;
source: PlatformCloudflareCredential['source'];
environmentVariable?: PlatformCloudflareCredential['environmentVariable'];
r2Buckets: ReadonlyArray<string>;
allowMissingR2Buckets?: boolean;
},
): Promise<void> {
const source =
input.source === 'saved'
? 'saved management token'
: input.source === 'environment'
? 'environment API token'
: 'Cloudflare browser login';
const label = platformOperatorCredentialLabel(input);
const name = describePlatformCredential(label);
const retry =
input.source === 'oauth'
? 'Run `void cloudflare login`, or set CLOUDFLARE_API_TOKEN for this account, then retry.'
: 'Set CLOUDFLARE_API_TOKEN for this account, then retry.';
: `Set ${input.environmentVariable ?? 'CLOUDFLARE_API_TOKEN'} for this account, then retry.`;
// Run every check, so one error lists every missing permission.
const denials: Array<PlatformCredentialDenial> = [];
let firstDenial: PlatformCloudflareApiError | undefined;
const deniedError = (denial: PlatformCloudflareApiError) =>
new Error(`platform: ${formatPlatformCredentialDenials(label, denials)}`, { cause: denial });
const check = async (
label: string,
what: string,
permission: string,
action: () => Promise<unknown>,
allowMissing = false,
) => {
): Promise<boolean> => {
try {
await action();
return true;
} catch (cause) {
const status = cause instanceof PlatformCloudflareApiError ? cause.status : null;
if (status === 404 && allowMissing) {
return;
return true;
}
if (status === 401 || status === 403) {
denials.push({ permission, request: what, status });
firstDenial ??= cause as PlatformCloudflareApiError;
return false;
}
const detail =
status === 401 || status === 403
? `Check that the credential is valid, scoped to this account, and includes ${permission}. ${retry}`
: status === 404
? 'Check the bucket name and account scope before retrying.'
: status === 429
? 'Cloudflare rate-limited this check. Retry shortly.'
: 'Retry the command after Cloudflare connectivity is restored.';
status === 404
? 'Check the bucket name and account scope before retrying.'
: status === 429
? 'Cloudflare rate-limited this check. Retry shortly.'
: 'Retry the command after Cloudflare connectivity is restored.';
// Report a denial already seen, so callers still see the rejected token.
if (firstDenial) {
throw deniedError(firstDenial);
}
throw new Error(
`platform: ${label} is unavailable${status === null ? '' : ` (HTTP ${status})`} using the ${source}. ${detail}`,
`platform: ${what} is unavailable${status === null ? '' : ` (HTTP ${status})`} using the ${name}. ${detail}`,
{ cause },
);
}
};
let accounts: ReadonlyArray<CloudflareAccount> = [];
await check('Cloudflare account access', 'Account → Account Settings → Read', async () => {
accounts = await client.listAccounts();
});
if (!accounts.some((account) => account.id === input.account.id)) {
const listedAccounts = await check(
'Cloudflare account access',
'Account → Account Settings → Read',
async () => {
accounts = await client.listAccounts();
},
);
if (listedAccounts && !accounts.some((account) => account.id === input.account.id)) {
throw new Error(
`platform: The ${source} cannot access Cloudflare account ${JSON.stringify(input.account.name)} (${input.account.id}). ${retry}`,
`platform: The ${name} cannot access Cloudflare account ${JSON.stringify(input.account.name)} (${input.account.id}). ${retry}`,
);
}
await check('Cloudflare Workers access', 'Account → Workers Scripts → Edit', () =>
client.listWorkerNames(input.account.id),
);
for (const name of new Set(input.r2Buckets)) {
for (const bucket of new Set(input.r2Buckets)) {
await check(
`R2 bucket ${JSON.stringify(name)}`,
`R2 bucket ${JSON.stringify(bucket)}`,
'Account → Workers R2 Storage → Edit',
() =>
client.request(
`/accounts/${encodeURIComponent(input.account.id)}/r2/buckets/${encodeURIComponent(name)}`,
`/accounts/${encodeURIComponent(input.account.id)}/r2/buckets/${encodeURIComponent(bucket)}`,
),
input.allowMissingR2Buckets,
);
}
if (firstDenial) {
throw deniedError(firstDenial);
}
}

/** Check Access inventory permissions before the installer starts provisioning. */
Expand Down Expand Up @@ -225,10 +263,11 @@ async function readExistingCredential(
dependencies: PlatformCloudflareAuthDependencies,
runWrangler: CloudflareAuthRunner,
): Promise<PlatformCloudflareCredential | null> {
const environmentToken =
process.env.CLOUDFLARE_API_TOKEN?.trim() || process.env.CF_API_TOKEN?.trim() || '';
if (environmentToken) {
return { source: 'environment', token: environmentToken };
for (const environmentVariable of ['CLOUDFLARE_API_TOKEN', 'CF_API_TOKEN'] as const) {
const environmentToken = process.env[environmentVariable]?.trim();
if (environmentToken) {
return { source: 'environment', environmentVariable, token: environmentToken };
}
}
const savedManagementToken = dependencies.savedManagementToken?.trim();
if (savedManagementToken) {
Expand Down
Loading