Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
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: 2 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -201,6 +201,8 @@ jobs:
run: |
npm ci
npm ci --prefix relay
- name: Validate opt-in D1 remote verification harness syntax
run: node --check cloud/scripts/verify-staging-d1.mjs
- name: Bundle staged Cloud Worker without bindings or deployment
run: npx wrangler deploy --config cloud/wrangler.ci.jsonc --dry-run --outdir dist/cloud

Expand Down
163 changes: 163 additions & 0 deletions cloud/scripts/verify-staging-d1.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,163 @@
#!/usr/bin/env node
/**
* Live Cloudflare D1 staging contract check, opt-in only.
*
* Requires CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID,
* MOTE_CLOUD_STAGING_DB_ID, and MOTE_STAGING_D1_CONFIRM=mote-cloud-staging.
* Never targets another database name and always deletes test fixture rows.
*
* This does NOT deploy a Worker, test real WebSockets or use Apple tokens.
*/
import assert from "node:assert/strict";
import { randomUUID } from "node:crypto";

const token = process.env.CLOUDFLARE_API_TOKEN;
const account = process.env.CLOUDFLARE_ACCOUNT_ID;
const dbId = process.env.MOTE_CLOUD_STAGING_DB_ID;
const confirmation = process.env.MOTE_STAGING_D1_CONFIRM;
if (!token || !/^[a-f0-9]{32}$/i.test(account ?? "") ||
!/^[a-f0-9-]{36}$/i.test(dbId ?? "") ||
confirmation !== "mote-cloud-staging") {
console.error("BLOCKED: missing staging-only Cloudflare credentials, IDs or confirmation.");
process.exit(2);
}

const base = `https://api.cloudflare.com/client/v4/accounts/${account}/d1/database/${dbId}`;
async function api(path = "", method = "GET", body) {
const response = await fetch(base + path, {
method,
headers: {
Authorization: `Bearer ${token}`,
...(body === undefined ? {} : { "Content-Type": "application/json" }),
},
...(body === undefined ? {} : { body: JSON.stringify(body) }),
signal: AbortSignal.timeout(12_000),
});
const payload = await response.json();
if (!response.ok || payload.success !== true ||
(Array.isArray(payload.result) && payload.result.some(r => r.success === false))) {
const error = new Error(`D1 query failed (HTTP ${response.status})`);
error.httpStatus = response.status;
error.details = payload.errors?.map(e => String(e.message ?? "")).join("; ") ?? "";
throw error;
}
return payload.result;
}
async function q(sql, params = []) {
return (await api("/query", "POST", { sql, params }))[0];
}

const accountA = randomUUID();
const accountB = randomUUID();
const ticketA = randomUUID();
const ticketB = randomUUID();
const deviceA = randomUUID();
const deviceB = randomUUID();
const now = Date.now();
const expiry = now + 300_000;
const accounts = [accountA, accountB];
const tickets = [ticketA, ticketB];
const hash = value => value.repeat(64);

async function main() {
const database = await api();
assert.equal(database.name, "mote-cloud-staging", "Refuse any non-staging D1 database");

const objects = await q(
"SELECT name FROM sqlite_master WHERE type='trigger' AND name LIKE 'cloud_pairing_%'",
);
assert.equal(objects.results.length, 3, "Required atomic pairing triggers missing");

const result = {};
try {
for (const [id, suffix] of [[accountA, "a"], [accountB, "b"]]) {
await q(
"INSERT INTO cloud_accounts (id,apple_subject,created_at_ms) VALUES (?,?,?)",
[id, `staging-fixture-${ticketA}-${suffix}`, String(now)],
);
}
const insertTicket = async (id, device, claimHash, pollHash, credentialHash) => {
await q(
`INSERT INTO cloud_pairing_tickets
(id,device_id,device_name,device_platform,claim_secret_hash,poll_secret_hash,
device_credential_hash,status,created_at_ms,expires_at_ms)
VALUES (?,?, 'P0C3 Fixture','windows',?,?,?,'pending',?,?)`,
[id, device, claimHash, pollHash, credentialHash, String(now), String(expiry)],
);
};
const approve = (id, owner) => q(
`UPDATE cloud_pairing_tickets
SET status='approved', claimed_by_account_id=?
WHERE id=? AND status='pending' AND expires_at_ms>?`,
[owner, id, String(now)],
);

await insertTicket(ticketA, deviceA, hash("a"), hash("b"), hash("c"));
const races = await Promise.allSettled([
approve(ticketA, accountA), approve(ticketA, accountB),
]);
const winning = races.filter(x => x.status === "fulfilled" &&
Number(x.value.meta?.changes) > 0);
assert.equal(winning.length, 1, "Exactly one approval must commit");

const ownerRow = await q(
"SELECT owner_account_id FROM cloud_devices WHERE id=?", [deviceA],
);
assert.equal(ownerRow.results.length, 1);
const owner = ownerRow.results[0].owner_account_id;
assert.ok(accounts.includes(owner));
result.triggerInclusiveChanges = winning[0].value.meta.changes;
result.exactlyOneWinner = true;

const replay = await approve(ticketA, owner === accountA ? accountB : accountA);
assert.equal(replay.meta.changes, 0, "Ticket must not transfer ownership");
result.replayRejected = true;

await insertTicket(ticketB, deviceB, hash("d"), hash("e"), hash("c"));
let collisionRejected = false;
try {
await approve(ticketB, accountB);
} catch (error) {
collisionRejected = error.httpStatus === 400;
}
assert.equal(collisionRejected, true, "Duplicate credential must abort");
const pending = await q(
"SELECT status FROM cloud_pairing_tickets WHERE id=?", [ticketB],
);
assert.equal(pending.results[0]?.status, "pending",
"Trigger failure must roll back ticket approval");
const devices = await q(
"SELECT COUNT(*) AS n FROM cloud_devices WHERE id IN (?,?)",
[deviceA, deviceB],
);
assert.equal(devices.results[0]?.n, 1);
result.collisionRollback = true;
console.log(JSON.stringify({ status: "D1_STAGING_PASS", ...result }));
} finally {
// Pending tickets are not owned by an account and must be removed
// separately. Use exact unique fixture IDs, never a broad DELETE.
try {
for (const id of tickets) {
await q("DELETE FROM cloud_pairing_tickets WHERE id=?", [id]);
}
for (const id of accounts) {
await q("DELETE FROM cloud_accounts WHERE id=?", [id]);
}
const remaining = await q(
`SELECT
(SELECT COUNT(*) FROM cloud_pairing_tickets WHERE id IN (?,?)) AS tickets,
(SELECT COUNT(*) FROM cloud_accounts WHERE id IN (?,?)) AS accounts,
(SELECT COUNT(*) FROM cloud_devices WHERE id IN (?,?)) AS devices`,
[...tickets, ...accounts, deviceA, deviceB],
);
assert.deepEqual(remaining.results[0], { tickets: 0, accounts: 0, devices: 0 });
} catch (error) {
console.error("CLEANUP_FAILED: synthetic fixture rows require manual review.");
throw error;
}
}
}
main().catch(error => {
console.error(`D1_STAGING_FAIL: ${error.message}`);
process.exitCode = 1;
});
104 changes: 104 additions & 0 deletions docs/cloud-p0c3a-real-d1.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,104 @@
# Mote Cloud P0C3A — Real Cloudflare D1 staging migration and pairing verification

**Date:** 2026-11-17 (Australia/Sydney)
**Phase:** P0C3A D1 REAL_STAGING_PARTIAL; Cloud Worker, Apple, WSS, mobile and desktop hardware are **NOT DEPLOYED/VERIFIED**.
**Parent:** P0C2 Draft PR #5. This change is intended as a stacked Draft PR.

## Verified actions

In the connected Cloudflare account, a **new and separate** D1 database named
`mote-cloud-staging` was created in the APAC region on 2026-11-16 UTC.
Existing databases and the older `mote-rc` Worker were inspected and not changed.

All three source-controlled migrations were applied **directly through the
Cloudflare D1 REST query API**, in this order:

1. `cloud/migrations/0001_core.sql` — 9 statements succeeded.
2. `cloud/migrations/0002_auth.sql` — 6 statements succeeded.
3. `cloud/migrations/0003_pairing_claim.sql` — 3 triggers succeeded.

A subsequent remote `sqlite_master` query verified 5 Cloud tables and all 3
`cloud_pairing_*` triggers were present.

A disposable **two-account D1 fixture** then tested:

- Concurrent approvals of one pending ticket: winner `meta.changes = 2` and
loser `meta.changes = 0`; only one account-owned device was created.
- Replay by the other account: no additional change.
- A second ticket attempting to register the same credential hash: the trigger
caused a constraint rejection; the ticket stayed pending and no second device
was inserted.
- Fixture cleanup: confirmed **0 test accounts, 0 devices, 0 tickets** remained
after removing pending tickets explicitly.

**Important real-D1 discovery:** D1's `meta.changes` counts the pairing ticket
UPDATE **plus** the trigger's device INSERT (2). The previous Node SQLite
adapter observed 1, so `CloudPairingRepository.approve` incorrectly checked
`changes === 1` and would return failure *after a successful committed claim*.
This PR fixes the result check to `Number.isSafeInteger(changes) && changes > 0`
for an UPDATE constrained to a unique ticket ID, and adds a regression test
that simulates the real D1 trigger-inclusive change count.

## Rerunnable verification

Use the opt-in `cloud/scripts/verify-staging-d1.mjs` script. It has an
**unskippable database-name guard** and creates only random synthetic fixture
rows, all cleaned up in `finally`.

Operator credentials must be exported as environment variables, **never
committed to Git or Notion**:

```sh
export CLOUDFLARE_API_TOKEN='(supply locally)'
export CLOUDFLARE_ACCOUNT_ID='(your Cloudflare account ID)'
export MOTE_CLOUD_STAGING_DB_ID='(verified staging D1 UUID)'
export MOTE_STAGING_D1_CONFIRM='mote-cloud-staging'
node cloud/scripts/verify-staging-d1.mjs
```

The script should report `D1_STAGING_PASS` with a single owner, replay
denial and collision rollback. Missing environment variables block it.
It never deploys a Worker, changes production tables, calls Apple, or locks a
desktop. Do not use database IDs from unrelated projects.

## Important migration tracking note

The above schema was installed via **direct D1 REST API statements**, NOT
`wrangler d1 migrations apply --remote`. This does **not** establish a
Wrangler-managed migration history. **Do not rerun** the three SQL files via
Wrangler against the populated `mote-cloud-staging` database: `CREATE TABLE`
and `CREATE TRIGGER` statements are not idempotent and will conflict.

Before adopting Wrangler as the ongoing migration runner, explicitly
**reconcile a reviewed migration baseline** with actual live `sqlite_master`
and Wrangler's documented migration tracking. Never insert fictional migration
records, reset the database, or run a destructive restore without review. Future
migration scripts must be independently versioned and verified.

## What is NOT verified (release blockers)

- No hosted Cloud Worker and no per-account Durable Object has been deployed.
The separate staging template still has placeholder IDs/client identifier and
`MOTE_CLOUD_STAGING_ENABLED=false`.
- No server-held staging gate or internal DO secret was configured; they must
not be placed in a public iOS/desktop app.
- No authentic Sign in with Apple token, iOS login flow or device QR UI was
tested.
- No real Cloudflare Worker/Durable Object WebSocket upgrade, hibernation,
command dispatch or physical macOS/Windows lock has been tested.
- No immediate device-revocation socket close, account deletion, distributed
throttling/cost controls, verified signing or App Store readiness.

## Next release-safe step

After reviewing the P0C2 security model, provide **operator-only** Cloud
staging credentials and real Apple client identifier, configure the isolated
Worker with the verified D1 binding and `CLOUD_TENANTS` (no old personal
Relay), and run a real Staging Worker/DO end-to-end test. Keep staging
**disabled/gated** until genuine Apple auth, revocation, two-account isolation
and physical device tests pass. The user-facing no-setup experience remains a
later P1–P3 deliverable.

References: [P0C2 realtime](cloud-p0c2-realtime.md),
[P0C1 atomic pairing](cloud-p0c1-pairing.md),
[Cloudflare D1 REST query API](https://developers.cloudflare.com/d1/best-practices/query-d1/).
7 changes: 6 additions & 1 deletion relay/src/cloud/pairingRepository.ts
Original file line number Diff line number Diff line change
Expand Up @@ -136,7 +136,12 @@ export class CloudPairingRepository {
WHERE d.id = cloud_pairing_tickets.device_id
)`,
).bind(accountId, ticketId, sha256(claimSecret), nowMs, accountId).run();
return result.meta.changes === 1;
// Cloudflare D1 counts the trigger's device INSERT as an additional
// change (2 total); Node SQLite's StatementResultingChanges reports
// only the ticket UPDATE (1). The WHERE clause targets the PRIMARY KEY
// and the trigger aborts atomically on failure, so any positive count
// means precisely one claim succeeded, whereas 0 means replay/race loss.
return Number.isSafeInteger(result.meta.changes) && result.meta.changes > 0;
} catch {
// Trigger insertion fails transactionally on revoked/duplicate credential.
return false;
Expand Down
42 changes: 36 additions & 6 deletions relay/test/cloudStaging.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -29,9 +29,10 @@ class SqliteStatement implements CloudD1Statement {
private readonly db: DatabaseSync,
private readonly sql: string,
private readonly args: SQLInputValue[] = [],
private readonly countTriggerWrites = false,
) {}
bind(...values: Array<string | number | null>): CloudD1Statement {
return new SqliteStatement(this.db, this.sql, values);
return new SqliteStatement(this.db, this.sql, values, this.countTriggerWrites);
}
async first<T>(): Promise<T | null> {
return (this.db.prepare(this.sql).get(...this.args) ?? null) as T | null;
Expand All @@ -41,16 +42,20 @@ class SqliteStatement implements CloudD1Statement {
}
async run(): Promise<{ meta: { changes: number } }> {
const result = this.db.prepare(this.sql).run(...this.args);
return { meta: { changes: Number(result.changes) } };
// D1 counts both UPDATE and trigger INSERT; node:sqlite counts just UPDATE.
const triggered = this.countTriggerWrites && result.changes > 0 &&
this.sql.includes("UPDATE cloud_pairing_tickets") &&
this.sql.includes("SET status = 'approved'");
return { meta: { changes: Number(result.changes) + (triggered ? 1 : 0) } };
}
}
function newDb(): { raw: DatabaseSync; binding: CloudD1Database } {
function newDb(countTriggerWrites = false): { raw: DatabaseSync; binding: CloudD1Database } {
const raw = new DatabaseSync(":memory:");
raw.exec("PRAGMA foreign_keys = ON");
raw.exec(db1);
raw.exec(db2);
raw.exec(db3);
return { raw, binding: { prepare: (sql) => new SqliteStatement(raw, sql) } };
return { raw, binding: { prepare: (sql) => new SqliteStatement(raw, sql, [], countTriggerWrites) } };
}

function appleToken(nonce: string, subject: string): string {
Expand All @@ -64,8 +69,8 @@ function appleToken(nonce: string, subject: string): string {
return `${message}.${sign("RSA-SHA256", Buffer.from(message), privateKey).toString("base64url")}`;
}

function harness() {
const { raw, binding } = newDb();
function harness(countTriggerWrites = false) {
const { raw, binding } = newDb(countTriggerWrites);
const env: CloudStagingEnv = {
CLOUD_DB: binding,
MOTE_CLOUD_STAGING_ENABLED: "true",
Expand Down Expand Up @@ -393,3 +398,28 @@ test("tenant admissions use the server-owned account and device secret, not call
), { allowed: false, status: 401, reason: "unauthenticated" });
} finally { raw.close(); }
});

test("real D1 counts trigger INSERT as a second change; approval still returns success", async () => {
const { raw, request, signIn } = harness(true);
try {
const owner = (await signIn("apple-real-d1-count-semantics")).login;
const desktop = desktopRegistration("77777777-7777-4777-8777-777777777777");
const ticket = await request("/cloud/v1/pairings", "POST", desktop.registration);
assert.equal(ticket.status, 201);
const approvalPath = "/cloud/v1/pairings/" + ticket.body.ticketId + "/approve";
const proof = { claimSecret: ticket.body.claimSecret, confirmedCode: ticket.body.verificationCode };
assert.deepEqual(await request(approvalPath, "POST", proof, owner.accessToken), {
status: 200, body: { status: "approved" },
});
const row = raw.prepare("SELECT status, claimed_by_account_id FROM cloud_pairing_tickets WHERE id = ?")
.get(ticket.body.ticketId) as { status: string; claimed_by_account_id: string };
assert.equal(row.status, "approved");
assert.equal(row.claimed_by_account_id, owner.accountId);
assert.equal((await request(approvalPath, "POST", proof, owner.accessToken)).status, 404);
assert.equal(
(raw.prepare("SELECT count(*) AS n FROM cloud_devices WHERE id = ?")
.get(desktop.registration.deviceId) as { n: number }).n,
1,
);
} finally { raw.close(); }
});
Loading