feat: age verification with an ID document (Didit), and closed registration (#4)
## Age verification with Didit A new provider (`apps/api/src/age/didit.ts`) behind the existing vendor-neutral age interface. A person verifies once with an ID document, a passive liveness check and a face match; after that, all their linked IMVU accounts count as adult. The hub keeps only "over 18": never the document, photo or birth date. - Webhooks are checked against Didit's signatures (the raw body or V2, with `-Previous` during secret rotation), and old ones are rejected. If the webhook has no decision, the hub fetches it from Didit. - A later answer replaces an earlier one. An approval that's taken back (say, after a manual review) becomes `revoked`. A check still in review stays pending. - Limits, for every provider: one unfinished check per person (starting again resumes it), at most 3 checks in 30 days, none once verified, and a monthly cap (`DIDIT_MONTHLY_LIMIT`, default 30: since 2026-11-01, Didit's free plan is $10 of credit a month, and a check costs $0.30). - People are only ever sent back to the hub's website. - The Account page gets an Age Verification card. - Configuration: `AGE_PROVIDERS=imvu,didit`, `DIDIT_API_KEY`, `DIDIT_WORKFLOW_ID`, `DIDIT_WEBHOOK_SECRET`. The webhook is `<API_URL>/api/v1/age/webhook/didit`. ## Closed registration Registration is open or closed. It's an admin's setting in the console, with its default from `REGISTRATION`. - When it's closed, new accounts can only sign in until a moderator approves them, or declines them (which deletes the account). - The website shows people who are waiting a waiting page, and the API treats them as signed out everywhere but `/me`. - The console gets a Waiting count, a Waiting for approval filter, Approve and Decline on a person's page, and a Registration setting. - The migration adds `user.approved` (existing accounts stay approved) and `hub_setting`. ## Testing - New tests cover Didit (with a fake Didit server), the limits, revocation, return addresses and registration. - `bun run test`: 35 pass. `bun run check-types` passes. - Checked locally: the account, waiting, sign-up and console pages render. - Not run against Didit itself yet. The sandbox workflow "T5DE Age Check" is published, and the next step is a real webhook once this is on staging. 🤖 Generated with [Claude Code](https://claude.com/claude-code) ## Age verification with Didit A new provider (`apps/api/src/age/didit.ts`) behind the existing vendor-neutral age interface. A person verifies once with an ID document, a passive liveness check and a face match; after that, all their linked IMVU accounts count as adult. The hub keeps only "over 18": never the document, photo or birth date. - Webhooks are checked against Didit's signatures (the raw body or V2, with `-Previous` during secret rotation), and old ones are rejected. If the webhook has no decision, the hub fetches it from Didit. - A later answer replaces an earlier one. An approval that's taken back (say, after a manual review) becomes `revoked`. A check still in review stays pending. - Limits, for every provider: one unfinished check per person (starting again resumes it), at most 3 checks in 30 days, none once verified, and a monthly cap (`DIDIT_MONTHLY_LIMIT`, default 30: since 2026-11-01, Didit's free plan is $10 of credit a month, and a check costs $0.30). - People are only ever sent back to the hub's website. - The Account page gets an Age Verification card. - Configuration: `AGE_PROVIDERS=imvu,didit`, `DIDIT_API_KEY`, `DIDIT_WORKFLOW_ID`, `DIDIT_WEBHOOK_SECRET`. The webhook is `<API_URL>/api/v1/age/webhook/didit`. ## Closed registration Registration is open or closed. It's an admin's setting in the console, with its default from `REGISTRATION`. - When it's closed, new accounts can only sign in until a moderator approves them, or declines them (which deletes the account). - The website shows people who are waiting a waiting page, and the API treats them as signed out everywhere but `/me`. - The console gets a Waiting count, a Waiting for approval filter, Approve and Decline on a person's page, and a Registration setting. - The migration adds `user.approved` (existing accounts stay approved) and `hub_setting`. ## Testing - New tests cover Didit (with a fake Didit server), the limits, revocation, return addresses and registration. - `bun run test`: 35 pass. `bun run check-types` passes. - Checked locally: the account, waiting, sign-up and console pages render. - Not run against Didit itself yet. The sandbox workflow "T5DE Age Check" is published, and the next step is a real webhook once this is on staging. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: dhkatz <[email protected]>
This commit was merged in pull request #4.
This commit is contained in:
dhkatz authored and 
dhkatz committed
1 parent
86ebe976ba
commit
d5cd2be5d0
28 files changed
+3260
-89
No files matched your search
+80
-17
@@ -1,7 +1,7 @@
|
||||
// Age verification, vendor-neutral: providers (IMVU, later phone wallets and Didit) plug in behind one interface,
|
||||
// results go in one table (age_check), and one rule says whether an IMVU account counts as adult.
|
||||
// See docs/design.md, "Age".
|
||||
import { and, eq, gt, inArray, isNull, lte, or, schema, type Database } from "@t5de/db";
|
||||
import { and, count, eq, gt, gte, inArray, isNull, lte, or, schema, type Database } from "@t5de/db";
|
||||
|
||||
const { ageCheck } = schema;
|
||||
|
||||
@@ -27,13 +27,19 @@ export type Started =
|
||||
|
||||
export type Provider = {
|
||||
id: string;
|
||||
/** Shown to people. */
|
||||
/** Shown to people: the way of checking, and who does it. */
|
||||
label: string;
|
||||
vendor: string;
|
||||
/** Whether it checks a person, or an IMVU account. */
|
||||
scope: "person" | "imvu_account";
|
||||
/** At most this many checks started each calendar month (UTC), for a provider's free allowance; none: no cap. */
|
||||
monthlyLimit?: number;
|
||||
start(subject: Subject, options: { returnURL: string }): Promise<Started>;
|
||||
/** Finishes a check from the provider's webhook; throws if the request isn't really from the provider. */
|
||||
webhook?(request: Request): Promise<{ ref: string; result: AgeResult | "failed" }>;
|
||||
/**
|
||||
* A check's answer from the provider's webhook, or null if it has none yet (still in progress or in review). Throws
|
||||
* if the request isn't really from the provider.
|
||||
*/
|
||||
webhook?(request: Request): Promise<{ ref: string; result: AgeResult | "failed" } | null>;
|
||||
/** Finishes a check the browser completed (wallets): the browser's response for ref. */
|
||||
complete?(ref: string, response: unknown): Promise<AgeResult | "failed">;
|
||||
/** Checks a subject again, for answers that can change. */
|
||||
@@ -41,6 +47,12 @@ export type Provider = {
|
||||
};
|
||||
|
||||
export class AgeError extends Error {}
|
||||
/** A check that can't be started now; the message is for the person. */
|
||||
export class AgeRefused extends Error {}
|
||||
|
||||
/** Checks of a person a provider will start for them in attemptWindow (failed and abandoned ones count). */
|
||||
export const attemptsPerPerson = 3;
|
||||
const attemptWindow = 30 * 24 * 60 * 60 * 1000;
|
||||
|
||||
const randomID = () => Buffer.from(crypto.getRandomValues(new Uint8Array(16))).toString("base64url");
|
||||
|
||||
@@ -56,7 +68,7 @@ export class AgeService {
|
||||
|
||||
/** The providers in use, for the website. */
|
||||
list() {
|
||||
return [...this.providers.values()].map((p) => ({ id: p.id, label: p.label, scope: p.scope }));
|
||||
return [...this.providers.values()].map((p) => ({ id: p.id, label: p.label, vendor: p.vendor, scope: p.scope }));
|
||||
}
|
||||
|
||||
provider(id: string): Provider {
|
||||
@@ -87,13 +99,25 @@ export class AgeService {
|
||||
await this.db.insert(ageCheck).values({ id: randomID(), ...values });
|
||||
}
|
||||
|
||||
/** Begins a check with a provider; checks answered at once are recorded now, the rest stay pending. */
|
||||
/**
|
||||
* Begins a check with a provider; checks answered at once are recorded now, the rest stay pending. A person whose
|
||||
* check is unfinished goes back to it (providers give the same session again); new checks of a person are
|
||||
* limited, per person and by the provider's monthly allowance.
|
||||
*/
|
||||
async start(subject: Subject, providerId: string, returnURL: string): Promise<Started> {
|
||||
const p = this.provider(providerId);
|
||||
const ofPerson = subject.imvuId === undefined;
|
||||
const pending = ofPerson ? await this.pendingCheck(subject.userId, p.id) : undefined;
|
||||
if (ofPerson) {
|
||||
if (await this.personAdult(subject.userId)) throw new AgeRefused("Your age is already verified.");
|
||||
if (!pending) await this.checkLimits(subject.userId, p);
|
||||
}
|
||||
const started = await p.start(subject, { returnURL });
|
||||
if (started.kind === "done") {
|
||||
await this.record(subject, p.id, started.result);
|
||||
} else {
|
||||
} else if (pending?.providerRef !== started.ref) {
|
||||
// An unfinished check the provider replaced with a new one (it expired there) won't be answered.
|
||||
if (pending) await this.db.update(ageCheck).set({ status: "failed", checkedAt: new Date() }).where(eq(ageCheck.id, pending.id));
|
||||
await this.db.insert(ageCheck).values({
|
||||
id: randomID(),
|
||||
userId: subject.userId,
|
||||
@@ -106,11 +130,55 @@ export class AgeService {
|
||||
return started;
|
||||
}
|
||||
|
||||
/** Finishes a pending check (from a webhook or the browser). */
|
||||
async finish(providerId: string, ref: string, result: AgeResult | "failed") {
|
||||
private async pendingCheck(userId: string, provider: string) {
|
||||
const [row] = await this.db
|
||||
.select()
|
||||
.from(ageCheck)
|
||||
.where(
|
||||
and(eq(ageCheck.userId, userId), eq(ageCheck.provider, provider), isNull(ageCheck.imvuId), eq(ageCheck.status, "pending")),
|
||||
);
|
||||
return row;
|
||||
}
|
||||
|
||||
private async personAdult(userId: string) {
|
||||
const now = new Date();
|
||||
return (await this.personChecks(userId)).some(
|
||||
(c) => c.status === "complete" && c.overEighteen && (c.expiresAt === null || c.expiresAt > now),
|
||||
);
|
||||
}
|
||||
|
||||
private async checkLimits(userId: string, p: Provider) {
|
||||
const started = async (...where: Parameters<typeof and>) =>
|
||||
(await this.db.select({ n: count() }).from(ageCheck).where(and(eq(ageCheck.provider, p.id), isNull(ageCheck.imvuId), ...where)))[0]!.n;
|
||||
const since = new Date(Date.now() - attemptWindow);
|
||||
if ((await started(eq(ageCheck.userId, userId), gte(ageCheck.createdAt, since))) >= attemptsPerPerson)
|
||||
throw new AgeRefused(`You've started ${attemptsPerPerson} checks in the last 30 days. Try again later.`);
|
||||
if (p.monthlyLimit !== undefined) {
|
||||
const now = new Date();
|
||||
const month = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), 1));
|
||||
if ((await started(gte(ageCheck.createdAt, month))) >= p.monthlyLimit)
|
||||
throw new AgeRefused("This month's ID checks are used up. Try again next month.");
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Finishes a check. From the browser (wallets), only a pending check; from a provider's webhook (anyStatus), also
|
||||
* one already answered, since the provider can change its answer (say, after a manual review). An adult answer
|
||||
* taken back is revoked.
|
||||
*/
|
||||
async finish(providerId: string, ref: string, result: AgeResult | "failed", { anyStatus = false } = {}) {
|
||||
const [row] = await this.db
|
||||
.select()
|
||||
.from(ageCheck)
|
||||
.where(and(eq(ageCheck.provider, providerId), eq(ageCheck.providerRef, ref)));
|
||||
if (!row || (!anyStatus && row.status !== "pending")) throw new AgeError("no such pending check");
|
||||
const done =
|
||||
result === "failed"
|
||||
? { status: "failed", overEighteen: false, checkedAt: new Date() }
|
||||
? {
|
||||
status: (row.status === "complete" && row.overEighteen) || row.status === "revoked" ? "revoked" : "failed",
|
||||
overEighteen: false,
|
||||
checkedAt: new Date(),
|
||||
}
|
||||
: {
|
||||
status: "complete",
|
||||
overEighteen: result.overEighteen,
|
||||
@@ -118,13 +186,8 @@ export class AgeService {
|
||||
checkedAt: new Date(),
|
||||
expiresAt: result.expiresAt ?? null,
|
||||
};
|
||||
const rows = await this.db
|
||||
.update(ageCheck)
|
||||
.set(done)
|
||||
.where(and(eq(ageCheck.provider, providerId), eq(ageCheck.providerRef, ref), eq(ageCheck.status, "pending")))
|
||||
.returning();
|
||||
if (rows.length === 0) throw new AgeError("no such pending check");
|
||||
return rows[0]!;
|
||||
const [updated] = await this.db.update(ageCheck).set(done).where(eq(ageCheck.id, row.id)).returning();
|
||||
return updated!;
|
||||
}
|
||||
|
||||
/** Removes an IMVU account's checks (it was unlinked or moved to another person). */
|
||||
|
||||
Reference in new issue
Block a user