Skip to content
Open
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
5 changes: 5 additions & 0 deletions CONFORMANCE.md
Original file line number Diff line number Diff line change
Expand Up @@ -51,6 +51,11 @@ not narrative. This does not promote any in-review binding above. See
[`backend/docs/retry-safe-messages.md`](backend/docs/retry-safe-messages.md) for
the guard, deployment requirements, crash limits, and executable checks.

The `UserEmails` table maps each account email to one user id so registration
can refuse a duplicate and login can find the account. It is private account
metadata, not part of the commons, the federation export, or the record. No
binding changes; see [`backend/README.md`](backend/README.md) for the rollout.

### Browser garden planner

The Next.js `/garden-planner` page is a member-local planning aid, not a ledger
Expand Down
29 changes: 28 additions & 1 deletion backend/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -81,7 +81,7 @@ Domain routes (when not in minimal mode):

## Data Model (DynamoDB tables)

- `Users`, `Keys`
- `Users`, `UserEmails`, `Keys`
- `Listings`, `Contracts`, `Transactions`
- `Conversations`, `Messages`
- `Notifications`
Expand All @@ -92,6 +92,33 @@ Each model file exports a `*_TABLE_NAME` and an item builder, e.g.:
- `models/user.js` → `USER_TABLE_NAME`, `createUserItem()`
- `models/transaction.js` → `TRANSACTION_TABLE_NAME`, `createTransactionItem()`

`UserEmails` (`models/userEmail.js`) holds one `{ email, userId }` item per
account email, trimmed and lower-cased. `/api/auth/register` and `POST /users`
write the claim and the user in one transaction, so a second account with the
same email gets `409`; login reads the claim instead of scanning `Users`.
`USER_EMAIL_TABLE_NAME` defaults to `UserEmails`. Before deploying, create the
table and claim the emails of existing accounts:

```sh
aws dynamodb create-table \
--table-name UserEmails \
--attribute-definitions AttributeName=email,AttributeType=S \
--key-schema AttributeName=email,KeyType=HASH \
--billing-mode PAY_PER_REQUEST
node scripts/claim-user-emails.js
```

Grant the backend `GetItem` and `PutItem` on `UserEmails`; the script also
scans `Users`. Run the script again after the deploy to claim accounts
registered in between. It only adds claims. An email shared by several existing
accounts gets a claim that names no account (`needsReview: true`), and the
script prints their ids: no new account can register that email, and none of
the listed accounts can log in until an operator decides which one owns it and
replaces the claim with `{ email, userId }`. Rows marked as imported from a
federation peer (`sourceNodeId`) are never claimed. Rows imported before peers
were marked carry no such field, so check where each listed id came from before
choosing an owner, and run the script only as part of this rollout.

## Chat & Streaming

Endpoints (used by the Chat UI):
Expand Down
18 changes: 17 additions & 1 deletion backend/__tests__/dynamodbClient.test.js
Original file line number Diff line number Diff line change
Expand Up @@ -11,9 +11,16 @@ test('DynamoDB adapter marshals records and preserves conditional error codes',
res.setHeader('Content-Type', 'application/x-amz-json-1.0');
if (requests.length === 1) res.end('{}');
else if (requests.length === 2) res.end(JSON.stringify({ Item: { id: { S: 'item' }, count: { N: '2' } } }));
else {
else if (requests.length === 3) {
res.statusCode = 400;
res.end(JSON.stringify({ __type: 'ConditionalCheckFailedException', message: 'missing item' }));
} else {
res.statusCode = 400;
res.end(JSON.stringify({
__type: 'TransactionCanceledException',
message: 'cancelled',
CancellationReasons: [{ Code: 'ConditionalCheckFailed' }, { Code: 'None' }],
}));
}
});
await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
Expand Down Expand Up @@ -41,4 +48,13 @@ test('DynamoDB adapter marshals records and preserves conditional error codes',
await assert.rejects(client.update({ TableName: 'Items', Key: { id: 'missing' } }).promise(), {
code: 'ConditionalCheckFailedException',
});
await assert.rejects(client.transactWrite({ TransactItems: [
{ Put: { TableName: 'Claims', Item: { id: 'item' }, ConditionExpression: 'attribute_not_exists(id)' } },
{ Put: { TableName: 'Items', Item: { id: 'item' } } },
] }).promise(), (error) => {
assert.equal(error.code, 'TransactionCanceledException');
assert.equal(error.CancellationReasons[0].Code, 'ConditionalCheckFailed');
return true;
});
assert.deepEqual(requests[3].TransactItems[0].Put.Item, { id: { S: 'item' } });
});
2 changes: 1 addition & 1 deletion backend/lib/dynamodbClient.js
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ const client = DynamoDBDocument.from(new DynamoDBClient({

// Keep the request interface used by existing models while using the supported SDK.
module.exports = Object.fromEntries(
['get', 'put', 'update', 'delete', 'query', 'scan', 'batchWrite'].map((method) => [
['get', 'put', 'update', 'delete', 'query', 'scan', 'batchWrite', 'transactWrite'].map((method) => [
method, (params) => ({ promise: async () => {
try {
return await client[method](params);
Expand Down
84 changes: 84 additions & 0 deletions backend/models/__tests__/userEmail.test.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,84 @@
const test = require('node:test');
const assert = require('node:assert/strict');

const docClient = require('../../lib/dynamodbClient');
const { memoryUserTables } = require('../../test-support/memoryUserTables');
const { claimExistingEmails, createUserWithEmail, findUserByEmail } = require('../userEmail');

function withUsers(users) {
const db = memoryUserTables();
for (const user of users) db.tables.Users.set(user.id, user);
Object.assign(docClient, db);
return db;
}

test('refuses to replace an existing account and leaves its email claim alone', async () => {
const db = withUsers([]);
assert.equal(await createUserWithEmail({ id: 'u1', email: 'ann@example.com' }), true);

await assert.rejects(createUserWithEmail({ id: 'u1', email: 'bob@example.com' }), {
code: 'TransactionCanceledException',
});
assert.deepEqual([...db.tables.UserEmails.values()], [{ email: 'ann@example.com', userId: 'u1' }]);
assert.deepEqual(db.tables.Users.get('u1'), { id: 'u1', email: 'ann@example.com' });
});

test('finds the claimed user with strongly consistent reads', async () => {
const db = withUsers([{ id: 'u1', email: 'ann@example.com' }]);
db.tables.UserEmails.set('ann@example.com', { email: 'ann@example.com', userId: 'u1' });
const reads = [];
docClient.get = (params) => { reads.push(params); return db.get(params); };

assert.equal((await findUserByEmail(' ANN@example.com ')).id, 'u1');
assert.deepEqual(reads.map(({ ConsistentRead }) => ConsistentRead), [true, true]);
});

test('claims normalised emails from every scan page and is safe to re-run', async () => {
const db = withUsers([
{ id: 'u1', email: ' Ann@Example.com' },
{ id: 'u2', email: 'bob@example.com' },
{ id: 'u3' },
]);

assert.deepEqual(await claimExistingEmails(), { claimed: 2, alreadyClaimed: 0, needsReview: [] });
assert.deepEqual(db.tables.UserEmails.get('ann@example.com'), { email: 'ann@example.com', userId: 'u1' });
assert.deepEqual(db.tables.UserEmails.get('bob@example.com'), { email: 'bob@example.com', userId: 'u2' });
assert.deepEqual(await claimExistingEmails(), { claimed: 0, alreadyClaimed: 2, needsReview: [] });
});

test('holds an email shared by several accounts for review and reports their ids', async () => {
const db = withUsers([
{ id: 'u1', email: 'john@example.com' },
{ id: 'u2', email: 'JOHN@example.com ' },
]);

assert.deepEqual(await claimExistingEmails(), { claimed: 0, alreadyClaimed: 0, needsReview: [['u1', 'u2']] });
assert.deepEqual([...db.tables.UserEmails.values()], [{ email: 'john@example.com', needsReview: true }]);
// A new registration cannot take the held email, and login finds no owner.
assert.equal(await createUserWithEmail({ id: 'u3', email: 'John@example.com' }), false);
assert.equal(db.tables.Users.has('u3'), false);
assert.equal(await findUserByEmail('john@example.com'), undefined);
// A re-run reports the same accounts and leaves the hold in place.
assert.deepEqual(await claimExistingEmails(), { claimed: 0, alreadyClaimed: 0, needsReview: [['u1', 'u2']] });
assert.deepEqual([...db.tables.UserEmails.values()], [{ email: 'john@example.com', needsReview: true }]);
});

test('never claims an email for a user row imported from a federation peer', async () => {
const db = withUsers([
{ id: 'u1', email: 'dana@example.com', sourceNodeId: 'peer-1' },
{ id: 'u2', email: 'erin@example.com' },
{ id: 'u3', email: 'erin@example.com', sourceNodeId: 'peer-1' },
]);

assert.deepEqual(await claimExistingEmails(), { claimed: 1, alreadyClaimed: 0, needsReview: [] });
assert.equal(db.tables.UserEmails.has('dana@example.com'), false);
assert.deepEqual(db.tables.UserEmails.get('erin@example.com'), { email: 'erin@example.com', userId: 'u2' });
});

test('reports an email already claimed by a different account', async () => {
const db = withUsers([{ id: 'u2', email: 'carl@example.com' }]);
db.tables.UserEmails.set('carl@example.com', { email: 'carl@example.com', userId: 'u9' });

assert.deepEqual(await claimExistingEmails(), { claimed: 0, alreadyClaimed: 0, needsReview: [['u9', 'u2']] });
assert.equal(db.tables.UserEmails.get('carl@example.com').userId, 'u9');
});
100 changes: 100 additions & 0 deletions backend/models/userEmail.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,100 @@
const docClient = require('../lib/dynamodbClient');
const { USER_TABLE_NAME } = require('./user');

// One item per normalised email, { email, userId }, so a conditional write can
// refuse a second account and login can find the owner without scanning Users.
const USER_EMAIL_TABLE_NAME = process.env.USER_EMAIL_TABLE_NAME || 'UserEmails';

function normalizeEmail(email) {
return typeof email === 'string' ? email.trim().toLowerCase() : '';
}

// Writes the email claim and a new user together; returns false if the email is
// taken. An id that already exists cancels the transaction and throws.
async function createUserWithEmail(user) {
try {
await docClient.transactWrite({
TransactItems: [
{ Put: {
TableName: USER_EMAIL_TABLE_NAME,
Item: { email: normalizeEmail(user.email), userId: user.id },
ConditionExpression: 'attribute_not_exists(email)',
} },
{ Put: { TableName: USER_TABLE_NAME, Item: user, ConditionExpression: 'attribute_not_exists(id)' } },
],
}).promise();
return true;
} catch (error) {
if (error.code === 'TransactionCanceledException' &&
error.CancellationReasons?.[0]?.Code === 'ConditionalCheckFailed') return false;
throw error;
}
}

async function findUserByEmail(email) {
const key = normalizeEmail(email);
if (!key) return undefined;
const { Item: claim } = await docClient.get({
TableName: USER_EMAIL_TABLE_NAME,
Key: { email: key },
ConsistentRead: true,
}).promise();
// A claim held for review names no account, so nobody logs in with it.
if (!claim?.userId) return undefined;
const { Item: user } = await docClient.get({
TableName: USER_TABLE_NAME,
Key: { id: claim.userId },
ConsistentRead: true,
}).promise();
return user;
}

// Claims the emails of accounts created before UserEmails existed. Safe to re-run;
// Users rows are never changed, and rows imported from a federation peer
// (sourceNodeId) are never claimed. An email held by more than one account gets a
// claim naming no account: registration cannot take it, and none of them can log
// in until an operator replaces it with the owner's userId.
async function claimExistingEmails() {
const owners = new Map();
let ExclusiveStartKey;
do {
const page = await docClient.scan({ TableName: USER_TABLE_NAME, ExclusiveStartKey }).promise();
for (const user of page.Items || []) {
const key = normalizeEmail(user.email);
if (key && !user.sourceNodeId) owners.set(key, [...(owners.get(key) || []), user.id]);
}
ExclusiveStartKey = page.LastEvaluatedKey;
} while (ExclusiveStartKey);

const report = { claimed: 0, alreadyClaimed: 0, needsReview: [] };
for (const [email, ids] of owners) {
const shared = ids.length > 1;
try {
await docClient.put({
TableName: USER_EMAIL_TABLE_NAME,
Item: shared ? { email, needsReview: true } : { email, userId: ids[0] },
ConditionExpression: 'attribute_not_exists(email)',
}).promise();
if (shared) report.needsReview.push(ids);
else report.claimed++;
} catch (error) {
if (error.code !== 'ConditionalCheckFailedException') throw error;
const { Item } = await docClient.get({
TableName: USER_EMAIL_TABLE_NAME,
Key: { email },
ConsistentRead: true,
}).promise();
if (!shared && Item?.userId === ids[0]) report.alreadyClaimed++;
else report.needsReview.push([...new Set([Item?.userId, ...ids].filter(Boolean))]);
}
}
return report;
}

module.exports = {
USER_EMAIL_TABLE_NAME,
normalizeEmail,
createUserWithEmail,
findUserByEmail,
claimExistingEmails,
};
Loading
Loading