@c9up/visa 0.1.0 → 0.1.1

package/src/stores/atlas.ts

@@ -0,0 +1,430 @@
+/**
+ * The store an application running atlas gets for free.
+ *
+ * Twelve methods, two of them atomic, is not something every application
+ * should write again — and the two that matter are exactly the ones a
+ * hand-written store gets subtly wrong. This is that code, once.
+ *
+ * It takes atlas' `db` service rather than importing atlas: the structural
+ * slice below is what the store calls and nothing more, so visa still installs
+ * without a data layer and the package stays as standalone as every other one
+ * here. Built on atlas' query builder rather than on SQL text, deliberately —
+ * dialects are atlas' problem, and it already solves them.
+ *
+ * Every credential arrives HASHED, as the contract states, so what this writes
+ * is what the rest of the package writes: a database copy is not a set of
+ * working tokens.
+ */
+
+import type { VisaStore } from "../store.js";
+import type {
+	AccessToken,
+	AuthorizationCode,
+	Client,
+	ClientAuthMethod,
+	Consent,
+	GrantType,
+	RefreshToken,
+} from "../types.js";
+
+/** A row as atlas hands it back. */
+type Row = Record<string, unknown>;
+
+/** The comparisons atlas' builder accepts. */
+type Operator = "=" | "!=" | ">" | ">=" | "<" | "<=";
+
+/**
+ * The slice of atlas' `DatabaseQueryBuilder` this store uses.
+ *
+ * Every read here fetches one row, so the slice asks for `first()` and not for
+ * the builder's thenable form. Nothing is declared that nothing calls.
+ */
+export interface AtlasQuery {
+	where(conditions: Row): AtlasQuery;
+	where(column: string, operator: Operator, value: unknown): AtlasQuery;
+	whereNull(column: string): AtlasQuery;
+	orderBy(column: string, direction?: "asc" | "desc"): AtlasQuery;
+	first(): Promise<Row | null>;
+	insert(data: Row): PromiseLike<unknown>;
+	/** Resolves to the number of rows affected, which is what the atomic paths read. */
+	update(data: Row): PromiseLike<number | Row[]>;
+	delete(): PromiseLike<number | Row[]>;
+}
+
+/** The slice of atlas' `db` service this store uses. */
+export interface AtlasDb {
+	from(table: string): AtlasQuery;
+	table(table: string): AtlasQuery;
+}
+
+/** Where each kind of row lives. Override one to fit a schema you do not own. */
+export interface AtlasStoreTables {
+	clients?: string;
+	authorizationCodes?: string;
+	accessTokens?: string;
+	refreshTokens?: string;
+	consents?: string;
+}
+
+const DEFAULT_TABLES = {
+	clients: "visa_clients",
+	authorizationCodes: "visa_authorization_codes",
+	accessTokens: "visa_access_tokens",
+	refreshTokens: "visa_refresh_tokens",
+	consents: "visa_consents",
+} as const;
+
+/**
+ * A list of strings, stored as JSON text.
+ *
+ * Text and not a native array type: three dialects are supported and only one
+ * of them has arrays. The round trip is explicit so a malformed value fails on
+ * read rather than becoming `[]` — a scope list that quietly empties is an
+ * authorisation bug, not a display one.
+ */
+function encodeList(values: readonly string[]): string {
+	return JSON.stringify(values);
+}
+
+function decodeList(value: unknown, column: string): string[] {
+	if (value === null || value === undefined) return [];
+	if (Array.isArray(value)) {
+		// A `json` column comes back parsed on some dialects and as text on others.
+		return value.filter((entry): entry is string => typeof entry === "string");
+	}
+	if (typeof value !== "string") {
+		throw new Error(`[visa] ${column} holds ${typeof value}, expected a list`);
+	}
+	const parsed: unknown = JSON.parse(value);
+	if (!Array.isArray(parsed)) {
+		throw new Error(`[visa] ${column} is not a JSON array: ${value}`);
+	}
+	return parsed.filter((entry): entry is string => typeof entry === "string");
+}
+
+/** A column that may be null, as a Date. */
+function decodeDate(value: unknown): Date | undefined {
+	if (value === null || value === undefined) return undefined;
+	if (value instanceof Date) return value;
+	if (typeof value === "number" || typeof value === "string") {
+		const date = new Date(value);
+		if (!Number.isNaN(date.getTime())) return date;
+	}
+	return undefined;
+}
+
+/** A column that must hold a date. */
+function requireDate(value: unknown, column: string): Date {
+	const date = decodeDate(value);
+	if (date === undefined) {
+		throw new Error(`[visa] ${column} is not a date: ${String(value)}`);
+	}
+	return date;
+}
+
+function requireString(value: unknown, column: string): string {
+	if (typeof value !== "string") {
+		throw new Error(`[visa] ${column} is not a string: ${String(value)}`);
+	}
+	return value;
+}
+
+function optionalString(value: unknown): string | undefined {
+	return typeof value === "string" && value !== "" ? value : undefined;
+}
+
+/**
+ * How many rows a write touched.
+ *
+ * `update()` answers a count, or the rows themselves when the caller asked for
+ * them. Only the count is ever asked for here, and the other shape is read as
+ * its length rather than assumed away.
+ */
+function affected(result: number | Row[]): number {
+	return typeof result === "number" ? result : result.length;
+}
+
+export class AtlasStore implements VisaStore {
+	readonly #db: AtlasDb;
+	readonly #tables: Required<AtlasStoreTables>;
+
+	constructor(db: AtlasDb, tables: AtlasStoreTables = {}) {
+		this.#db = db;
+		this.#tables = {
+			clients: tables.clients ?? DEFAULT_TABLES.clients,
+			authorizationCodes:
+				tables.authorizationCodes ?? DEFAULT_TABLES.authorizationCodes,
+			accessTokens: tables.accessTokens ?? DEFAULT_TABLES.accessTokens,
+			refreshTokens: tables.refreshTokens ?? DEFAULT_TABLES.refreshTokens,
+			consents: tables.consents ?? DEFAULT_TABLES.consents,
+		};
+	}
+
+	async findClient(id: string): Promise<Client | null> {
+		const row = await this.#db.from(this.#tables.clients).where({ id }).first();
+		if (row === null) return null;
+		const secretHash = optionalString(row.secret_hash);
+		return {
+			id: requireString(row.id, "id"),
+			name: requireString(row.name, "name"),
+			...(secretHash === undefined ? {} : { secretHash }),
+			redirectUris: decodeList(row.redirect_uris, "redirect_uris"),
+			grantTypes: decodeList(row.grant_types, "grant_types").filter(
+				isGrantType,
+			),
+			scopes: decodeList(row.scopes, "scopes"),
+			tokenEndpointAuthMethod: readAuthMethod(row.token_endpoint_auth_method),
+			...(row.trusted === true || row.trusted === 1 ? { trusted: true } : {}),
+		};
+	}
+
+	/** Persist a registered client. Not on the contract — what `registerClient` writes through. */
+	async saveClient(client: Client): Promise<void> {
+		await this.#db.table(this.#tables.clients).insert({
+			id: client.id,
+			name: client.name,
+			secret_hash: client.secretHash ?? null,
+			redirect_uris: encodeList(client.redirectUris),
+			grant_types: encodeList(client.grantTypes),
+			scopes: encodeList(client.scopes),
+			token_endpoint_auth_method: client.tokenEndpointAuthMethod,
+			trusted: client.trusted === true,
+			created_at: new Date(),
+		});
+	}
+
+	async saveAuthorizationCode(code: AuthorizationCode): Promise<void> {
+		await this.#db.table(this.#tables.authorizationCodes).insert({
+			code_hash: code.codeHash,
+			client_id: code.clientId,
+			user_id: code.userId,
+			redirect_uri: code.redirectUri,
+			scopes: encodeList(code.scopes),
+			code_challenge: code.codeChallenge,
+			code_challenge_method: code.codeChallengeMethod,
+			expires_at: code.expiresAt,
+			consumed_at: code.consumedAt ?? null,
+			nonce: code.nonce ?? null,
+			created_at: new Date(),
+		});
+	}
+
+	async findAuthorizationCode(
+		codeHash: string,
+	): Promise<AuthorizationCode | null> {
+		const row = await this.#db
+			.from(this.#tables.authorizationCodes)
+			.where({ code_hash: codeHash })
+			.first();
+		if (row === null) return null;
+		const consumedAt = decodeDate(row.consumed_at);
+		const nonce = optionalString(row.nonce);
+		return {
+			codeHash: requireString(row.code_hash, "code_hash"),
+			clientId: requireString(row.client_id, "client_id"),
+			userId: requireString(row.user_id, "user_id"),
+			redirectUri: requireString(row.redirect_uri, "redirect_uri"),
+			scopes: decodeList(row.scopes, "scopes"),
+			codeChallenge: requireString(row.code_challenge, "code_challenge"),
+			codeChallengeMethod:
+				row.code_challenge_method === "plain" ? "plain" : "S256",
+			expiresAt: requireDate(row.expires_at, "expires_at"),
+			...(consumedAt === undefined ? {} : { consumedAt }),
+			...(nonce === undefined ? {} : { nonce }),
+		};
+	}
+
+	/**
+	 * One UPDATE, guarded by `consumed_at IS NULL`.
+	 *
+	 * The single-use guarantee lives in that one statement: two requests racing
+	 * with the same code both reach the database, and only the one that finds
+	 * the row still unconsumed is allowed to write it. Reading and then writing
+	 * would let both through.
+	 */
+	async consumeAuthorizationCode(codeHash: string, at: Date): Promise<boolean> {
+		const result = await this.#db
+			.from(this.#tables.authorizationCodes)
+			.where({ code_hash: codeHash })
+			.whereNull("consumed_at")
+			.update({ consumed_at: at });
+		return affected(result) === 1;
+	}
+
+	async saveAccessToken(token: AccessToken): Promise<void> {
+		await this.#db.table(this.#tables.accessTokens).insert({
+			token_hash: token.tokenHash,
+			client_id: token.clientId,
+			user_id: token.userId ?? null,
+			scopes: encodeList(token.scopes),
+			expires_at: token.expiresAt,
+			revoked_at: token.revokedAt ?? null,
+			last_used_at: token.lastUsedAt ?? null,
+			family_id: token.familyId ?? null,
+			created_at: new Date(),
+		});
+	}
+
+	async findAccessToken(tokenHash: string): Promise<AccessToken | null> {
+		const row = await this.#db
+			.from(this.#tables.accessTokens)
+			.where({ token_hash: tokenHash })
+			.first();
+		if (row === null) return null;
+		const userId = optionalString(row.user_id);
+		const revokedAt = decodeDate(row.revoked_at);
+		const lastUsedAt = decodeDate(row.last_used_at);
+		const familyId = optionalString(row.family_id);
+		return {
+			tokenHash: requireString(row.token_hash, "token_hash"),
+			clientId: requireString(row.client_id, "client_id"),
+			...(userId === undefined ? {} : { userId }),
+			scopes: decodeList(row.scopes, "scopes"),
+			expiresAt: requireDate(row.expires_at, "expires_at"),
+			...(revokedAt === undefined ? {} : { revokedAt }),
+			...(lastUsedAt === undefined ? {} : { lastUsedAt }),
+			...(familyId === undefined ? {} : { familyId }),
+		};
+	}
+
+	async revokeAccessToken(tokenHash: string, at: Date): Promise<void> {
+		await this.#db
+			.from(this.#tables.accessTokens)
+			.where({ token_hash: tokenHash })
+			.whereNull("revoked_at")
+			.update({ revoked_at: at });
+	}
+
+	async touchAccessToken(tokenHash: string, at: Date): Promise<void> {
+		await this.#db
+			.from(this.#tables.accessTokens)
+			.where({ token_hash: tokenHash })
+			.update({ last_used_at: at });
+	}
+
+	async saveRefreshToken(token: RefreshToken): Promise<void> {
+		await this.#db.table(this.#tables.refreshTokens).insert({
+			token_hash: token.tokenHash,
+			family_id: token.familyId,
+			client_id: token.clientId,
+			user_id: token.userId ?? null,
+			scopes: encodeList(token.scopes),
+			expires_at: token.expiresAt,
+			consumed_at: token.consumedAt ?? null,
+			revoked_at: token.revokedAt ?? null,
+			created_at: new Date(),
+		});
+	}
+
+	async findRefreshToken(tokenHash: string): Promise<RefreshToken | null> {
+		const row = await this.#db
+			.from(this.#tables.refreshTokens)
+			.where({ token_hash: tokenHash })
+			.first();
+		if (row === null) return null;
+		const userId = optionalString(row.user_id);
+		const consumedAt = decodeDate(row.consumed_at);
+		const revokedAt = decodeDate(row.revoked_at);
+		return {
+			tokenHash: requireString(row.token_hash, "token_hash"),
+			familyId: requireString(row.family_id, "family_id"),
+			clientId: requireString(row.client_id, "client_id"),
+			...(userId === undefined ? {} : { userId }),
+			scopes: decodeList(row.scopes, "scopes"),
+			expiresAt: requireDate(row.expires_at, "expires_at"),
+			...(consumedAt === undefined ? {} : { consumedAt }),
+			...(revokedAt === undefined ? {} : { revokedAt }),
+		};
+	}
+
+	/** Same one-statement guarantee as a code: rotation depends on it. */
+	async consumeRefreshToken(tokenHash: string, at: Date): Promise<boolean> {
+		const result = await this.#db
+			.from(this.#tables.refreshTokens)
+			.where({ token_hash: tokenHash })
+			.whereNull("consumed_at")
+			.update({ consumed_at: at });
+		return affected(result) === 1;
+	}
+
+	/**
+	 * End a family: the refresh tokens AND the access tokens they bought.
+	 *
+	 * Both, because revoking only the refresh half would leave an access token
+	 * already minted alive for its full lifetime — which is most of what this
+	 * revocation exists to prevent.
+	 */
+	async revokeFamily(familyId: string, at: Date): Promise<void> {
+		await this.#db
+			.from(this.#tables.refreshTokens)
+			.where({ family_id: familyId })
+			.whereNull("revoked_at")
+			.update({ revoked_at: at });
+		await this.#db
+			.from(this.#tables.accessTokens)
+			.where({ family_id: familyId })
+			.whereNull("revoked_at")
+			.update({ revoked_at: at });
+	}
+
+	async findConsent(userId: string, clientId: string): Promise<Consent | null> {
+		const row = await this.#db
+			.from(this.#tables.consents)
+			.where({ user_id: userId, client_id: clientId })
+			.first();
+		if (row === null) return null;
+		return {
+			userId: requireString(row.user_id, "user_id"),
+			clientId: requireString(row.client_id, "client_id"),
+			scopes: decodeList(row.scopes, "scopes"),
+			grantedAt: requireDate(row.granted_at, "granted_at"),
+		};
+	}
+
+	/**
+	 * Record a consent, replacing what was there.
+	 *
+	 * Delete then insert rather than an upsert: the dialects spell an upsert
+	 * three different ways, and re-granting is not a hot path.
+	 */
+	async saveConsent(consent: Consent): Promise<void> {
+		await this.#db
+			.from(this.#tables.consents)
+			.where({ user_id: consent.userId, client_id: consent.clientId })
+			.delete();
+		await this.#db.table(this.#tables.consents).insert({
+			user_id: consent.userId,
+			client_id: consent.clientId,
+			scopes: encodeList(consent.scopes),
+			granted_at: consent.grantedAt,
+		});
+	}
+
+	/** Drop what has expired and can no longer be presented. */
+	async prune(now: Date): Promise<void> {
+		for (const table of [
+			this.#tables.authorizationCodes,
+			this.#tables.accessTokens,
+			this.#tables.refreshTokens,
+		]) {
+			await this.#db.from(table).where("expires_at", "<", now).delete();
+		}
+	}
+}
+
+function isGrantType(value: string): value is GrantType {
+	return (
+		value === "authorization_code" ||
+		value === "refresh_token" ||
+		value === "client_credentials"
+	);
+}
+
+function readAuthMethod(value: unknown): ClientAuthMethod {
+	if (value === "client_secret_basic" || value === "client_secret_post") {
+		return value;
+	}
+	// A row holding nothing usable is read as a public client, which is the
+	// method that grants the least.
+	return "none";
+}

package/src/stores/memory.ts

@@ -70,6 +70,11 @@ export class MemoryStore implements VisaStore {
 		if (token !== undefined) token.revokedAt = at;
 	}
 
+	async touchAccessToken(tokenHash: string, at: Date): Promise<void> {
+		const token = this.#accessTokens.get(tokenHash);
+		if (token !== undefined) token.lastUsedAt = at;
+	}
+
 	async saveRefreshToken(token: RefreshToken): Promise<void> {
 		this.#refreshTokens.set(token.tokenHash, token);
 	}

package/src/types.ts

@@ -69,6 +69,13 @@ export interface AccessToken {
 	scopes: string[];
 	expiresAt: Date;
 	revokedAt?: Date;
+	/**
+	 * When this token was last presented, if the store records it.
+	 *
+	 * What an "Applications connectées" screen shows next to each authorisation,
+	 * and what tells a dormant token from a live one.
+	 */
+	lastUsedAt?: Date;
 	/**
 	 * The refresh family this token was minted in, when there is one.
 	 *

package/stubs/database/migrations/9000_create_visa_tables.stub

@@ -0,0 +1,103 @@
+---
+to: database/migrations/9000_create_visa_tables.ts
+---
+import { Migration } from "@c9up/atlas";
+
+/**
+ * What the authorization server keeps.
+ *
+ * Every credential column holds a HASH, never the value that was handed out —
+ * a dump of these tables is not a set of working tokens.
+ *
+ * Two portability rules are followed deliberately and should survive an edit:
+ *
+ * No `t.timestamps()`. It emits `DEFAULT (NOW())`, which is not a sqlite
+ * function and fails at `migration:run` on a fresh sqlite app. Every timestamp
+ * here is written explicitly by the store instead.
+ *
+ * Every string that is a primary key or an index stays well inside MySQL's
+ * InnoDB utf8mb4 limit of 3072 bytes (768 characters). A hash is 64 characters
+ * of hex; an identifier is capped at 255.
+ */
+export default class CreateVisaTables extends Migration {
+	async up() {
+		this.schema.createTable("visa_clients", (t) => {
+			t.string("id", 255).primary();
+			t.string("name", 255).notNullable();
+			// Null for a public client — a SPA or a native app has no secret to keep.
+			t.string("secret_hash", 255).nullable();
+			t.json("redirect_uris").notNullable();
+			t.json("grant_types").notNullable();
+			t.json("scopes").notNullable();
+			t.string("token_endpoint_auth_method", 32).notNullable();
+			t.boolean("trusted").notNullable();
+			t.timestamp("created_at").notNullable();
+		});
+
+		this.schema.createTable("visa_authorization_codes", (t) => {
+			t.string("code_hash", 64).primary();
+			t.string("client_id", 255).notNullable();
+			t.string("user_id", 255).notNullable();
+			t.text("redirect_uri").notNullable();
+			t.json("scopes").notNullable();
+			t.string("code_challenge", 128).notNullable();
+			t.string("code_challenge_method", 10).notNullable();
+			t.timestamp("expires_at").notNullable();
+			// Set the moment it is exchanged: the single-use guarantee is an
+			// UPDATE guarded on this column being null.
+			t.timestamp("consumed_at").nullable();
+			t.string("nonce", 255).nullable();
+			t.timestamp("created_at").notNullable();
+			t.index("user_id");
+		});
+
+		this.schema.createTable("visa_access_tokens", (t) => {
+			t.string("token_hash", 64).primary();
+			t.string("client_id", 255).notNullable();
+			// Null for `client_credentials`: there is no user behind that grant.
+			t.string("user_id", 255).nullable();
+			t.json("scopes").notNullable();
+			t.timestamp("expires_at").notNullable();
+			t.timestamp("revoked_at").nullable();
+			t.timestamp("last_used_at").nullable();
+			// The refresh family this token was minted in. Indexed because
+			// revoking a leaked family reads every token by it.
+			t.string("family_id", 64).nullable();
+			t.timestamp("created_at").notNullable();
+			t.index("family_id");
+			t.index("user_id");
+		});
+
+		this.schema.createTable("visa_refresh_tokens", (t) => {
+			t.string("token_hash", 64).primary();
+			t.string("family_id", 64).notNullable();
+			t.string("client_id", 255).notNullable();
+			t.string("user_id", 255).nullable();
+			t.json("scopes").notNullable();
+			t.timestamp("expires_at").notNullable();
+			t.timestamp("consumed_at").nullable();
+			t.timestamp("revoked_at").nullable();
+			t.timestamp("created_at").notNullable();
+			t.index("family_id");
+			t.index("user_id");
+		});
+
+		this.schema.createTable("visa_consents", (t) => {
+			t.string("user_id", 255).notNullable();
+			t.string("client_id", 255).notNullable();
+			t.json("scopes").notNullable();
+			t.timestamp("granted_at").notNullable();
+			// One consent per pair: asking twice for the same thing is the bug
+			// this table exists to prevent.
+			t.primary(["user_id", "client_id"]);
+		});
+	}
+
+	async down() {
+		this.schema.dropTable("visa_consents");
+		this.schema.dropTable("visa_refresh_tokens");
+		this.schema.dropTable("visa_access_tokens");
+		this.schema.dropTable("visa_authorization_codes");
+		this.schema.dropTable("visa_clients");
+	}
+}