@c9up/visa 0.1.1 → 0.1.3

package/src/stores/atlas.ts

@@ -45,6 +45,8 @@ export interface AtlasQuery {
 	whereNull(column: string): AtlasQuery;
 	orderBy(column: string, direction?: "asc" | "desc"): AtlasQuery;
 	first(): Promise<Row | null>;
+	/** Run the select and return every row — atlas' `exec()`. */
+	exec(): Promise<Row[]>;
 	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[]>;
@@ -205,6 +207,7 @@ export class AtlasStore implements VisaStore {
 			expires_at: code.expiresAt,
 			consumed_at: code.consumedAt ?? null,
 			nonce: code.nonce ?? null,
+			resources: encodeList(code.resources ?? []),
 			created_at: new Date(),
 		});
 	}
@@ -231,6 +234,7 @@ export class AtlasStore implements VisaStore {
 			expiresAt: requireDate(row.expires_at, "expires_at"),
 			...(consumedAt === undefined ? {} : { consumedAt }),
 			...(nonce === undefined ? {} : { nonce }),
+			...listOrNothing("resources", row.resources),
 		};
 	}
 
@@ -261,6 +265,7 @@ export class AtlasStore implements VisaStore {
 			revoked_at: token.revokedAt ?? null,
 			last_used_at: token.lastUsedAt ?? null,
 			family_id: token.familyId ?? null,
+			audience: encodeList(token.audience ?? []),
 			created_at: new Date(),
 		});
 	}
@@ -270,21 +275,7 @@ export class AtlasStore implements VisaStore {
 			.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 }),
-		};
+		return row === null ? null : readAccessToken(row);
 	}
 
 	async revokeAccessToken(tokenHash: string, at: Date): Promise<void> {
@@ -312,6 +303,7 @@ export class AtlasStore implements VisaStore {
 			expires_at: token.expiresAt,
 			consumed_at: token.consumedAt ?? null,
 			revoked_at: token.revokedAt ?? null,
+			resources: encodeList(token.resources ?? []),
 			created_at: new Date(),
 		});
 	}
@@ -334,6 +326,7 @@ export class AtlasStore implements VisaStore {
 			expiresAt: requireDate(row.expires_at, "expires_at"),
 			...(consumedAt === undefined ? {} : { consumedAt }),
 			...(revokedAt === undefined ? {} : { revokedAt }),
+			...listOrNothing("resources", row.resources),
 		};
 	}
 
@@ -400,6 +393,54 @@ export class AtlasStore implements VisaStore {
 		});
 	}
 
+	async listConsents(userId: string): Promise<Consent[]> {
+		const rows = await this.#db
+			.from(this.#tables.consents)
+			.where({ user_id: userId })
+			.orderBy("granted_at", "desc")
+			.exec();
+		return rows.map((row) => ({
+			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"),
+		}));
+	}
+
+	/** Expired ones included — see the contract for why. */
+	async listAccessTokens(userId: string): Promise<AccessToken[]> {
+		const rows = await this.#db
+			.from(this.#tables.accessTokens)
+			.where({ user_id: userId })
+			.orderBy("expires_at", "desc")
+			.exec();
+		return rows.map(readAccessToken);
+	}
+
+	async revokeAccessFor(
+		userId: string,
+		clientId: string,
+		at: Date,
+	): Promise<void> {
+		for (const table of [
+			this.#tables.accessTokens,
+			this.#tables.refreshTokens,
+		]) {
+			await this.#db
+				.from(table)
+				.where({ user_id: userId, client_id: clientId })
+				.whereNull("revoked_at")
+				.update({ revoked_at: at });
+		}
+	}
+
+	async deleteConsent(userId: string, clientId: string): Promise<void> {
+		await this.#db
+			.from(this.#tables.consents)
+			.where({ user_id: userId, client_id: clientId })
+			.delete();
+	}
+
 	/** Drop what has expired and can no longer be presented. */
 	async prune(now: Date): Promise<void> {
 		for (const table of [
@@ -412,6 +453,49 @@ export class AtlasStore implements VisaStore {
 	}
 }
 
+/** One access-token row, as the contract's shape. */
+function readAccessToken(row: Row): AccessToken {
+	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 }),
+		...listOrNothing("audience", row.audience),
+	};
+}
+
+/**
+ * A list column, present in the object only when it holds something.
+ *
+ * Empty and absent mean the same thing for an audience — unbound — and the
+ * contract spells that as absent, so an empty column must not become `[]` or
+ * a round trip would stop matching what went in.
+ */
+function listOrNothing(
+	key: "audience",
+	value: unknown,
+): { audience?: string[] };
+function listOrNothing(
+	key: "resources",
+	value: unknown,
+): { resources?: string[] };
+function listOrNothing(
+	key: "audience" | "resources",
+	value: unknown,
+): { audience?: string[]; resources?: string[] } {
+	const list = decodeList(value, key);
+	if (list.length === 0) return {};
+	return key === "audience" ? { audience: list } : { resources: list };
+}
+
 function isGrantType(value: string): value is GrantType {
 	return (
 		value === "authorization_code" ||

package/src/stores/memory.ts

@@ -70,6 +70,39 @@ export class MemoryStore implements VisaStore {
 		if (token !== undefined) token.revokedAt = at;
 	}
 
+	async listConsents(userId: string): Promise<Consent[]> {
+		return [...this.#consents.values()].filter(
+			(consent) => consent.userId === userId,
+		);
+	}
+
+	async listAccessTokens(userId: string): Promise<AccessToken[]> {
+		return [...this.#accessTokens.values()].filter(
+			(token) => token.userId === userId,
+		);
+	}
+
+	async revokeAccessFor(
+		userId: string,
+		clientId: string,
+		at: Date,
+	): Promise<void> {
+		for (const token of this.#accessTokens.values()) {
+			if (token.userId !== userId || token.clientId !== clientId) continue;
+			if (token.revokedAt === undefined) token.revokedAt = at;
+		}
+		for (const token of this.#refreshTokens.values()) {
+			if (token.userId !== userId || token.clientId !== clientId) continue;
+			if (token.revokedAt === undefined) token.revokedAt = at;
+		}
+	}
+
+	async deleteConsent(userId: string, clientId: string): Promise<void> {
+		// The same NUL-separated key `saveConsent` writes: a colon would make
+		// `a:b` + `c` collide with `a` + `b:c`.
+		this.#consents.delete(`${userId}\u0000${clientId}`);
+	}
+
 	async touchAccessToken(tokenHash: string, at: Date): Promise<void> {
 		const token = this.#accessTokens.get(tokenHash);
 		if (token !== undefined) token.lastUsedAt = at;

package/src/token.ts

@@ -14,11 +14,18 @@ import {
 } from "./clients.js";
 import { hashMatches, hashSecret, randomToken, sha256 } from "./crypto.js";
 import { OAuthError } from "./errors.js";
+import {
+	narrowResources,
+	readResourceParameter,
+	validateResources,
+} from "./resource.js";
 import type { VisaStore } from "./store.js";
 import type { Client, GrantType, TokenResponse } from "./types.js";
 
 export interface TokenOptions {
 	accessTokenTtlSeconds?: number;
+	/** The resources this server issues tokens for — see `AuthorizeOptions`. */
+	resourcesSupported?: readonly string[];
 	refreshTokenTtlSeconds?: number;
 	/** Hand out refresh tokens at all. */
 	issueRefreshTokens?: boolean;
@@ -135,12 +142,23 @@ async function exchangeCode(
 		throw invalid;
 	}
 
+	// RFC 8707: a request may narrow the resources the code was bound to,
+	// never widen them — the user saw the list at authorization time.
+	const resources = narrowResources(
+		validateResources(
+			readResourceParameter(request.resource),
+			options.resourcesSupported,
+		),
+		record.resources ?? [],
+	);
+
 	return issue(
 		{
 			client,
 			userId: record.userId,
 			scopes: record.scopes,
 			familyId: codeFamily(record.codeHash),
+			resources,
 		},
 		store,
 		options,
@@ -215,6 +233,13 @@ async function exchangeRefresh(
 			...(record.userId === undefined ? {} : { userId: record.userId }),
 			scopes,
 			familyId: record.familyId,
+			resources: narrowResources(
+				validateResources(
+					readResourceParameter(request.resource),
+					options.resourcesSupported,
+				),
+				record.resources ?? [],
+			),
 		},
 		store,
 		options,
@@ -258,7 +283,16 @@ async function clientCredentials(
 	}
 	const scopes = resolveScopes(asString(request.scope), client);
 	return issue(
-		{ client, scopes },
+		{
+			client,
+			scopes,
+			// No user consented to a list here, so the request IS the list —
+			// checked against what this server issues for, and nothing wider.
+			resources: validateResources(
+				readResourceParameter(request.resource),
+				options.resourcesSupported,
+			),
+		},
 		store,
 		{ ...options, issueRefreshTokens: false },
 		now,
@@ -270,6 +304,8 @@ interface Issued {
 	userId?: string;
 	scopes: string[];
 	familyId?: string;
+	/** RFC 8707 — what the token is for. Empty means unbound. */
+	resources?: string[];
 }
 
 /** Mint the pair and store both, hashed. */
@@ -290,6 +326,9 @@ async function issue(
 		scopes: grant.scopes,
 		expiresAt: new Date(now.getTime() + accessTtl * 1000),
 		...(grant.familyId === undefined ? {} : { familyId: grant.familyId }),
+		...(grant.resources === undefined || grant.resources.length === 0
+			? {}
+			: { audience: grant.resources }),
 	});
 
 	const response: TokenResponse = {
@@ -315,6 +354,11 @@ async function issue(
 		...(grant.userId === undefined ? {} : { userId: grant.userId }),
 		scopes: grant.scopes,
 		expiresAt: new Date(now.getTime() + refreshTtl * 1000),
+		// Carried so a rotation can narrow from the same list the code bound —
+		// without it, the second token of a session would be unbound.
+		...(grant.resources === undefined || grant.resources.length === 0
+			? {}
+			: { resources: grant.resources }),
 	});
 	response.refresh_token = refreshToken;
 	return response;

package/src/types.ts

@@ -32,6 +32,15 @@ export interface Client {
 	name: string;
 	/** Hashed. The plaintext is shown once, at registration, and never stored. */
 	secretHash?: string;
+	/**
+	 * When the secret stops working (RFC 7591 §3.2.1).
+	 *
+	 * Absent means it does not expire, which is the common case. Present, it is
+	 * enforced at authentication — a `client_secret_expires_at` answered at
+	 * registration and never checked afterwards is a promise the server makes
+	 * and does not keep.
+	 */
+	secretExpiresAt?: Date;
 	redirectUris: string[];
 	grantTypes: GrantType[];
 	/** What this client may ever ask for; a request narrows it, never widens it. */
@@ -57,6 +66,13 @@ export interface AuthorizationCode {
 	expiresAt: Date;
 	/** Set the moment it is exchanged, so a replay is detectable (§7.5.1). */
 	consumedAt?: Date;
+	/**
+	 * The resources this code may buy a token for (RFC 8707).
+	 *
+	 * Bound here rather than at the token endpoint: the user saw the request
+	 * that named them, and the exchange may narrow the list but never widen it.
+	 */
+	resources?: string[];
 	/** Carried through to the id_token when OIDC lands. */
 	nonce?: string;
 }
@@ -76,6 +92,15 @@ export interface AccessToken {
 	 * and what tells a dormant token from a live one.
 	 */
 	lastUsedAt?: Date;
+	/**
+	 * Which resources this token is for (RFC 8707).
+	 *
+	 * Absent means unbound — a token for everything, which is what every token
+	 * was before a client started asking. A resource server checks it against
+	 * its own identifier, so a token that travelled to the wrong one is refused
+	 * there instead of being honoured.
+	 */
+	audience?: string[];
 	/**
 	 * The refresh family this token was minted in, when there is one.
 	 *
@@ -102,6 +127,8 @@ export interface RefreshToken {
 	expiresAt: Date;
 	consumedAt?: Date;
 	revokedAt?: Date;
+	/** The resources a token minted from this one may be for (RFC 8707). */
+	resources?: string[];
 }
 
 /** What a user agreed to give a client, so they are asked once. */
@@ -112,6 +139,29 @@ export interface Consent {
 	grantedAt: Date;
 }
 
+/**
+ * One application a user has authorised, as a "connected applications" screen
+ * shows it.
+ *
+ * The unit is the APPLICATION, not the token: a person authorised an
+ * application, and the tokens come and go under that one decision. Upstream's
+ * equivalent listing is per token because it has no clients; here a user with
+ * four live tokens for one application has authorised one thing, and seeing
+ * four rows would be a lie about what revoking does.
+ */
+export interface AuthorizedApplication {
+	clientId: string;
+	/** The client's registered name, or its id when the client is gone. */
+	name: string;
+	/** What was granted — the consent, not what any one token happens to carry. */
+	scopes: string[];
+	grantedAt: Date;
+	/** The most recent use across this application's tokens, if any was used. */
+	lastUsedAt?: Date;
+	/** Whether anything issued to it is still usable right now. */
+	active: boolean;
+}
+
 /** The token endpoint's success body (§4.1.4). */
 export interface TokenResponse {
 	access_token: string;
@@ -138,4 +188,6 @@ export interface IntrospectionResponse {
 	exp?: number;
 	iat?: number;
 	token_type?: "Bearer";
+	/** Which resources the token is for — RFC 8707 §3 names introspection as where this travels. */
+	aud?: string[];
 }

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

@@ -47,6 +47,10 @@ export default class CreateVisaTables extends Migration {
 			// UPDATE guarded on this column being null.
 			t.timestamp("consumed_at").nullable();
 			t.string("nonce", 255).nullable();
+			// RFC 8707 — which resources a token bought with this code may be
+			// for. Empty means unbound, which is every code a client sent no
+			// `resource` with.
+			t.json("resources").notNullable();
 			t.timestamp("created_at").notNullable();
 			t.index("user_id");
 		});
@@ -63,6 +67,9 @@ export default class CreateVisaTables extends Migration {
 			// 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();
+			// RFC 8707 — what this token is for. Empty means unbound, and a
+			// resource server accepts it; bound, it is refused anywhere else.
+			t.json("audience").notNullable();
 			t.timestamp("created_at").notNullable();
 			t.index("family_id");
 			t.index("user_id");
@@ -77,6 +84,8 @@ export default class CreateVisaTables extends Migration {
 			t.timestamp("expires_at").notNullable();
 			t.timestamp("consumed_at").nullable();
 			t.timestamp("revoked_at").nullable();
+			// Carried so a rotation narrows from the same list the code bound.
+			t.json("resources").notNullable();
 			t.timestamp("created_at").notNullable();
 			t.index("family_id");
 			t.index("user_id");