Files
WebHooker/server/lib/web/invites.ts
T
翅膀 81af2053c0 fix(group): preserve identity through lifecycle
Group names are mutable and reusable, so they cannot own durable
state. Preserve immutable identities across lifecycle operations and
commit invite use with membership under transaction-time guards.
2026-10-23 23:23:27 +08:00

522 lines
20 KiB
TypeScript

import type { Env, Group } from "../types";
import {
loadGroups,
updateGroup,
memberMatches,
memberRole,
memberRoleStatement,
normalizeGroupMembers,
} from "./groups";
import {
acceptedKey,
claimOnce,
confirmClaim,
idempotencyStore,
recordStatement,
} from "../lib/idempotency";
import { canUseD1 } from "../storage/d1";
import { ConfigConflictError } from "../storage/config-store";
import { log } from "../lib/log";
export interface Invite {
groupId: string;
/** Invited users can never be owners; only admins or viewers. */
role: "admin" | "viewer";
expiresAt: number;
createdBy: string;
note?: string;
/**
* The invited group's immutable `instance` id. A group later re-created
* under the same id has another instance, so the invite never admits anyone
* to it. Absent on invites created before instances existed.
*/
groupInstance?: string;
/**
* Who issued it: a super admin, or a member who must still be an owner of
* the group when the invite is used — an owner removed meanwhile cannot
* have it let anyone in. Absent on older invites.
*/
issuer?: { super: true } | { userId: string; login: string };
}
/** The invite belongs to an earlier group that had the same id. */
class StaleInviteError extends Error {}
/**
* The login is still on a member entry bound to another account (a member
* who renamed since). Adding a second entry with that login would be dropped
* as a duplicate — a "successful" join without access — so the owner must
* clear the stale entry first.
*/
class MemberConflictError extends Error {}
function revokedKey(token: string): string {
return `invite-revoked:${token}`;
}
/** How long an invite stays claimed while one acceptance is being processed. */
const INVITE_CLAIM_SECONDS = 120;
/** Invites are valid for seven days; their KV keys live exactly that long. */
export const INVITE_LIFETIME_MS = 7 * 86400_000;
const INDEX_TTL = INVITE_LIFETIME_MS / 1000;
/** KV TTL (seconds) for an invite expiring at `expiresAt` (KV minimum: 60). */
function ttlFor(expiresAt: number): number {
return Math.max(60, Math.ceil((expiresAt - Date.now()) / 1000));
}
function generateInviteToken(): string {
const bytes = new Uint8Array(32);
crypto.getRandomValues(bytes);
return Array.from(bytes)
.map((b) => b.toString(16).padStart(2, "0"))
.join("");
}
function inviteKey(token: string): string {
return `invite:${token}`;
}
/**
* Per-group index of invite tokens. Listing pending invites reads this key
* instead of `kv.list({ prefix })`, which is eventually consistent and can
* lag behind a fresh write by minutes — the index keeps listing reliable.
*/
function indexKey(groupId: string): string {
return `invite:group:${groupId}`;
}
/**
* Tokens of a group's index. A failed read propagates: taken for an empty
* index, it would be written back without the existing tokens, leaving those
* invites valid but unlisted (and so impossible to revoke from the console).
*/
async function readIndex(kv: KVNamespace, groupId: string): Promise<string[]> {
const raw = await kv.get<string[]>(indexKey(groupId), "json");
return Array.isArray(raw) ? raw : [];
}
async function writeIndex(kv: KVNamespace, groupId: string, tokens: string[]): Promise<void> {
await kv.put(indexKey(groupId), JSON.stringify(tokens), { expirationTtl: INDEX_TTL });
}
/**
* Per-invite membership key, written on its own (no read-modify-write): two
* invites created at once can both lose their index entry to the other's
* index write, but never their marker. Listing reads both — the index for
* fresh writes, the markers (an eventually consistent `list`) for durability.
*/
function markerPrefix(groupId: string): string {
return `invite:by-group:${groupId}:`;
}
function listMarkers(kv: KVNamespace, groupId: string): Promise<string[]> {
return listPrefix(kv, markerPrefix(groupId));
}
/**
* Per-invite key under the issuing group's instance: it never moves, so the
* group finds its invites even when moving them to a new id after a rename
* failed halfway.
*/
function instancePrefix(instance: string): string {
return `invite:by-instance:${instance}:`;
}
async function listPrefix(kv: KVNamespace, prefix: string): Promise<string[]> {
const tokens: string[] = [];
let cursor: string | undefined;
do {
const page = await kv.list({ prefix, cursor });
for (const k of page.keys) {
if (k.name.startsWith(prefix)) tokens.push(k.name.slice(prefix.length));
}
cursor = page.list_complete ? undefined : (page as { cursor?: string }).cursor;
} while (cursor);
return tokens;
}
/** Every token listed for a group: by its index, its id markers or its instance markers. */
async function groupTokens(kv: KVNamespace, groupId: string, instance?: string): Promise<string[]> {
const [indexed, marked, owned] = await Promise.all([
readIndex(kv, groupId),
listMarkers(kv, groupId),
instance ? listPrefix(kv, instancePrefix(instance)) : Promise.resolve([]),
]);
return [...new Set([...indexed, ...marked, ...owned])];
}
/**
* Write the index without the given tokens — only when it lists any of them:
* KV writes are the scarcest quota (Workers Free), and an unchanged index
* needs no rewrite.
*/
async function dropFromIndex(kv: KVNamespace, groupId: string, gone: string[]): Promise<void> {
const current = await readIndex(kv, groupId);
const kept = current.filter((t) => !gone.includes(t));
if (kept.length !== current.length) await writeIndex(kv, groupId, kept);
}
/** Remove every listing link of an invite that is gone (index, id and instance markers). */
async function removeFromIndex(kv: KVNamespace, invite: Invite, token: string): Promise<void> {
await kv.delete(`${markerPrefix(invite.groupId)}${token}`);
if (invite.groupInstance) await kv.delete(`${instancePrefix(invite.groupInstance)}${token}`);
await dropFromIndex(kv, invite.groupId, [token]);
}
export async function createInvite(kv: KVNamespace, invite: Invite): Promise<string> {
const token = generateInviteToken();
const ttl = { expirationTtl: ttlFor(invite.expiresAt) };
await kv.put(inviteKey(token), JSON.stringify(invite), ttl);
await kv.put(`${markerPrefix(invite.groupId)}${token}`, "1", ttl);
if (invite.groupInstance) {
await kv.put(`${instancePrefix(invite.groupInstance)}${token}`, "1", ttl);
}
const tokens = await readIndex(kv, invite.groupId);
tokens.push(token);
await writeIndex(kv, invite.groupId, tokens);
return token;
}
/** The invite, or null when it does not exist (any more). Read errors propagate. */
export async function getInvite(kv: KVNamespace, token: string): Promise<Invite | null> {
const raw = await kv.get<Invite>(inviteKey(token), "json");
if (!raw) return null;
if (Date.now() > raw.expiresAt) {
await kv.delete(inviteKey(token));
await removeFromIndex(kv, raw, token);
return null;
}
return raw;
}
export async function consumeInvite(kv: KVNamespace, token: string): Promise<void> {
const raw = await kv.get<Invite>(inviteKey(token), "json");
await kv.delete(inviteKey(token));
if (raw) await removeFromIndex(kv, raw, token);
}
/**
* Whether an invite was issued by this very group, not by an earlier group
* that had the same id (its index may outlive a failed cleanup). An invite from
* before instances belongs to the group that had its id back then (`legacyId`).
*/
function issuedBy(
invite: Invite,
group: Pick<Group, "instance" | "legacyId"> | undefined,
): boolean {
if (!group?.instance) return true;
if (invite.groupInstance) return invite.groupInstance === group.instance;
return group.legacyId === invite.groupId;
}
/**
* All pending (unexpired) invites of a group, via the per-group index. With
* the group given, invites of an earlier group under the same id are left
* out (and removed): their links must not reach the new group's owners.
*/
export async function listInvites(
kv: KVNamespace,
groupId: string,
group?: Pick<Group, "instance" | "legacyId">,
): Promise<Array<Invite & { token: string }>> {
// Read errors propagate (the console shows a failure, not "no invites"),
// and only tokens whose invite is known to be gone are pruned.
// A pre-instance group may still have invites filed under the id it had
// back then (a rename whose invite move failed).
const formerId = group?.legacyId && group.legacyId !== groupId ? group.legacyId : undefined;
const tokens = [
...new Set([
...(await groupTokens(kv, groupId, group?.instance)),
...(formerId ? await groupTokens(kv, formerId) : []),
]),
];
const out: Array<Invite & { token: string }> = [];
const stale: string[] = [];
for (const token of tokens) {
const invite = await getInvite(kv, token);
// Also the group's own invites still filed under a former id (a rename
// whose invite move failed): they are usable, so they must be listed.
const ours =
invite != null &&
issuedBy(invite, group) &&
(invite.groupId === groupId ||
(group?.instance != null && invite.groupInstance === group.instance) ||
(formerId != null && !invite.groupInstance && invite.groupId === formerId));
if (invite && ours) {
out.push({ ...invite, token });
} else {
// Not this group's (gone, or issued by a former holder of the id — which
// may live on under another id): only the listing link to this id goes;
// the invite itself is not ours to revoke and expires on its own.
await kv.delete(`${markerPrefix(groupId)}${token}`);
// A gone invite's marker under this group's instance goes too, or every
// later listing would find (and clean up after) it again until it expires.
if (!invite && group?.instance) {
await kv.delete(`${instancePrefix(group.instance)}${token}`);
}
stale.push(token);
}
}
// Re-read: an invite created meanwhile must stay listed.
if (stale.length > 0) await dropFromIndex(kv, groupId, stale);
return out;
}
/**
* Revoke an invite. With `db`, the revocation is first recorded in the
* idempotency store (for the invite's lifetime): an acceptance already past
* its KV read checks it inside its member write, so it cannot still join.
*/
export async function revokeInvite(
kv: KVNamespace,
token: string,
db?: D1Database,
guards?: (db: D1Database) => D1PreparedStatement[],
): Promise<void> {
const raw = await kv.get<Invite>(inviteKey(token), "json");
if (db) {
const ttl = ttlFor(raw?.expiresAt ?? Date.now() + INVITE_LIFETIME_MS);
if (guards && canUseD1(db)) {
// The revocation record commits only while the guards hold (e.g. the
// revoking owner still is one): a request authorized before a role
// change can no longer act after it.
await db.batch([...guards(db), recordStatement(db, revokedKey(token), ttl)]);
} else {
await idempotencyStore(db, kv).claim(revokedKey(token), ttl);
}
}
await kv.delete(inviteKey(token));
if (raw) await removeFromIndex(kv, raw, token);
}
/**
* Re-point every pending invite of a group to its new id (group rename).
* Best-effort: a failure leaves the old invites in place (they will be
* rejected as group-missing after the rename).
*/
export async function migrateInvites(
kv: KVNamespace,
from: string,
to: string,
group?: Pick<Group, "instance" | "legacyId">,
): Promise<void> {
try {
const tokens = await groupTokens(kv, from);
if (tokens.length === 0) {
await kv.delete(indexKey(from));
return;
}
const moved: string[] = [];
for (const token of tokens) {
const invite = await kv.get<Invite>(inviteKey(token), "json");
// Only the renamed group's own invites move (a former group's leftovers
// stay behind); they get its instance, so they keep working under the
// new id even when they date from before instances.
if (invite && invite.groupId === from && issuedBy(invite, group)) {
const groupInstance = invite.groupInstance ?? group?.instance;
const ttl = { expirationTtl: ttlFor(invite.expiresAt) };
await kv.put(
inviteKey(token),
JSON.stringify({ ...invite, groupId: to, groupInstance }),
ttl,
);
await kv.put(`${markerPrefix(to)}${token}`, "1", ttl);
if (groupInstance) await kv.put(`${instancePrefix(groupInstance)}${token}`, "1", ttl);
await kv.delete(`${markerPrefix(from)}${token}`);
moved.push(token);
}
}
const kept = (await readIndex(kv, to)).filter((t) => !moved.includes(t));
await kv.put(indexKey(to), JSON.stringify([...kept, ...moved]), {
expirationTtl: INDEX_TTL,
});
await kv.delete(indexKey(from));
} catch (err) {
log.warn({ err, from, to }, "Failed to migrate invites on group rename");
}
}
/** Revoke every pending invite of a deleted group. */
export async function deleteGroupInvites(
kv: KVNamespace,
groupId: string,
group?: Pick<Group, "instance" | "legacyId">,
): Promise<void> {
const instance = group?.instance;
try {
for (const token of await groupTokens(kv, groupId, instance)) {
// Only the deleted group's own invites are revoked: one listed under
// its id may have been issued by a group that lives on under another.
const invite = await kv.get<Invite>(inviteKey(token), "json");
if (
invite &&
issuedBy(invite, group) &&
(invite.groupId === groupId || (instance != null && invite.groupInstance === instance))
) {
await kv.delete(inviteKey(token));
}
await kv.delete(`${markerPrefix(groupId)}${token}`);
if (instance) await kv.delete(`${instancePrefix(instance)}${token}`);
}
await kv.delete(indexKey(groupId));
} catch (err) {
log.warn({ err, groupId }, "Failed to delete invites of a removed group");
}
}
/**
* Adds the accepting user to the invited group (or upgrades their role when
* they are already a viewer) and consumes the invite. The invited role is
* never an owner — ownership stays with the inviter's discretion.
*
* The invite is claimed atomically before the membership changes, so two
* people accepting the same link at once cannot both join; the member write is
* a compare-and-swap on the group, so it never reverts a concurrent edit.
*/
export async function acceptInvite(
env: Pick<Env, "KV" | "DB">,
token: string,
userId: string,
login: string,
/** The login identity checks may use ("" when it is not trusted as this user's). */
matchLogin = login,
): Promise<
| { ok: true; groupId: string; groupInstance?: string; role: "admin" | "viewer" }
| { ok: false; reason: "invalid" | "group-missing" | "conflict" }
> {
const kv = env.KV;
const invite = await getInvite(kv, token);
if (!invite) return { ok: false, reason: "invalid" };
const claims = idempotencyStore(env.DB, kv);
const claimKey = `invite-used:${token}`;
// A short claim while joining, confirmed for the invite's lifetime once
// used: an attempt that fails and cannot give the claim back blocks the
// invite for a couple of minutes, not until it expires.
if ((await claimOnce(claims, claimKey, INVITE_CLAIM_SECONDS)) !== "claimed") {
return { ok: false, reason: "invalid" };
}
if (await claims.has(revokedKey(token))) {
await claims.release(claimKey).catch(() => undefined);
return { ok: false, reason: "invalid" };
}
let joined = false;
let joinedId: string | undefined;
let joinedInstance: string | undefined;
/** The member who issued the invite is no longer an owner (it is void then). */
const issuerGone = async (): Promise<boolean> => {
const by = invite.issuer && "userId" in invite.issuer ? invite.issuer : null;
if (!by) return false;
const group = (await loadGroups(kv, { fresh: true })).find((g) =>
invite.groupInstance ? g.instance === invite.groupInstance : g.legacyId === invite.groupId,
);
return !group || memberRole(group, by.userId, by.login) !== "owner";
};
try {
// The invited group is the instance the invite was issued for, under
// whatever id it has now. An invite from before instances only applies to
// a group that existed back then, never to one created since.
const groups = await loadGroups(kv, { fresh: true });
const target = invite.groupInstance
? groups.find((g) => g.instance === invite.groupInstance)
: groups.find((g) => g.legacyId === invite.groupId);
// Its group instance is gone for good: the invite can never be used.
if (!target && invite.groupInstance) throw new StaleInviteError();
if (!target) return { ok: false, reason: "group-missing" };
// The invite is confirmed as used in the same transaction that adds the
// member — only when that write went through (`changes()`: the member
// update right before; a lost compare-and-swap changes nothing) and the
// member is there after it: no crash between the two can leave a member
// added and the invite still open, nor a retried write consume it unused.
const confirmWithJoin = (db: D1Database): D1PreparedStatement[] => [
db
.prepare(
`INSERT INTO dedup_keys (key, claimed_at, expires_at)
SELECT ?, ?, ? WHERE changes() > 0 AND EXISTS (
SELECT 1 FROM (SELECT id, CASE WHEN json_valid(data) THEN data ELSE '{}' END AS data FROM d1_groups) g, json_each(g.data, '$.members') m
WHERE g.id = ? AND json_extract(m.value, '$.userId') = ?)
ON CONFLICT(key) DO UPDATE SET expires_at = excluded.expires_at`,
)
.bind(acceptedKey(claimKey), Date.now(), invite.expiresAt, target.id, userId),
];
// And it only commits while the invite is unused and not revoked: an
// earlier acceptance whose answer was lost (its claim given back, its use
// committed), or a revocation that landed after the KV read, aborts it.
const issuer = invite.issuer && "userId" in invite.issuer ? invite.issuer : null;
const unusedGuard = (db: D1Database): D1PreparedStatement[] => [
db
.prepare(
"SELECT CASE WHEN EXISTS (SELECT 1 FROM dedup_keys WHERE key IN (?, ?) AND expires_at > ?) THEN json('invite used') ELSE 1 END AS ok",
)
.bind(acceptedKey(claimKey), revokedKey(token), Date.now()),
...(issuer
? [memberRoleStatement(db, target.id, issuer.userId, issuer.login, ["owner"])]
: []),
];
const updated = await updateGroup(
kv,
target.id,
(group) => {
const sameInstance = invite.groupInstance
? group.instance === invite.groupInstance
: group.legacyId === invite.groupId;
if (!sameInstance) throw new StaleInviteError();
const members = normalizeGroupMembers(group);
const idx = members.findIndex((m) => memberMatches(m, userId, matchLogin));
if (idx >= 0) {
if (invite.role === "admin" && members[idx]!.role === "viewer") {
members[idx]!.role = "admin";
}
members[idx]!.userId ??= userId;
} else {
if (members.some((m) => m.login.toLowerCase() === login.toLowerCase())) {
throw new MemberConflictError();
}
// Bound to the account that accepted, not to its (renamable) login.
members.push({ login, role: invite.role, userId });
}
return {
...group,
members,
adminIds: members.filter((m) => m.role === "owner").map((m) => m.login),
};
},
{ guards: unusedGuard, after: confirmWithJoin },
);
joined = updated != null;
joinedId = updated?.id;
joinedInstance = updated?.instance;
} catch (err) {
// The invite stays usable once the owner resolved the conflict.
if (err instanceof MemberConflictError) return { ok: false, reason: "conflict" };
// Used meanwhile (by an acceptance whose answer was lost).
if (
err instanceof ConfigConflictError &&
((await claims.has(acceptedKey(claimKey))) ||
(await claims.has(revokedKey(token))) ||
(await issuerGone()))
) {
return { ok: false, reason: "invalid" };
}
if (!(err instanceof StaleInviteError)) throw err;
await consumeInvite(kv, token);
return { ok: false, reason: "invalid" };
} finally {
if (!joined) await claims.release(claimKey).catch(() => undefined);
}
if (!joined) return { ok: false, reason: "group-missing" };
await confirmClaim(claims, claimKey, ttlFor(invite.expiresAt)).catch((err: unknown) =>
log.warn({ err }, "Failed to confirm an invite claim"),
);
await consumeInvite(kv, token);
return {
ok: true,
groupId: joinedId ?? invite.groupId,
groupInstance: joinedInstance,
role: invite.role,
};
}