@c9up/visa 0.1.1 → 0.1.2

package/src/resource.ts

@@ -0,0 +1,123 @@
+/**
+ * Which resource a token is for (RFC 8707).
+ *
+ * A token with no stated audience is a token for everything. Send it to the
+ * wrong server — or let a compromised one replay it — and every other resource
+ * that trusts the same issuer accepts it. The `resource` parameter is how a
+ * client says "this one is for the calendar API", and how the calendar API
+ * refuses one minted for somebody else.
+ *
+ * Read off the RFC rather than recalled: the value MUST be an absolute URI
+ * without a fragment (§2), it MAY repeat, and a resource the server does not
+ * accept is refused with `invalid_target` (§2) — not `invalid_request`, which
+ * would tell a client its request was malformed when it was merely aimed
+ * somewhere it may not go.
+ */
+
+import { OAuthError } from "./errors.js";
+
+/**
+ * Normalise however the parameter arrived into a list.
+ *
+ * A form body gives one value or several under the same name, and a query
+ * string the same; both are `resource=` repeated, which parsers hand over
+ * either way.
+ */
+export function readResourceParameter(value: unknown): string[] {
+	if (value === undefined || value === null) return [];
+	if (Array.isArray(value)) {
+		return value.filter((entry): entry is string => typeof entry === "string");
+	}
+	return typeof value === "string" && value !== "" ? [value] : [];
+}
+
+/**
+ * Check each one, and refuse the request if any is unusable.
+ *
+ * `invalid_target` for every rejection here, including a malformed URI: §2
+ * names that code for "cannot parse the provided value(s)" as well as for a
+ * resource the server will not issue for.
+ */
+export function validateResources(
+	requested: readonly string[],
+	accepted?: readonly string[],
+): string[] {
+	const resources: string[] = [];
+	for (const value of requested) {
+		let url: URL;
+		try {
+			url = new URL(value);
+		} catch {
+			throw new OAuthError(
+				"invalid_target",
+				`resource must be an absolute URI: ${value}`,
+			);
+		}
+		if (url.hash !== "") {
+			throw new OAuthError(
+				"invalid_target",
+				`resource must not carry a fragment: ${value}`,
+			);
+		}
+		// §2 SHOULD NOT include a query, and recognises that some cases need
+		// one — so it travels rather than being refused or stripped. Stripping
+		// would hand back a token for a resource nobody asked for.
+		if (accepted !== undefined && !accepted.includes(value)) {
+			throw new OAuthError(
+				"invalid_target",
+				`this server does not issue tokens for ${value}`,
+			);
+		}
+		if (!resources.includes(value)) resources.push(value);
+	}
+	return resources;
+}
+
+/**
+ * What a token request may narrow to.
+ *
+ * A refresh or an exchange may ask for fewer resources than were authorised,
+ * never for more — the same rule scopes follow, and for the same reason: the
+ * user agreed to a set, and a later request must not widen it.
+ */
+export function narrowResources(
+	requested: readonly string[],
+	granted: readonly string[],
+): string[] {
+	if (requested.length === 0) return [...granted];
+	if (granted.length === 0) {
+		// Nothing was bound at authorization time, so there is nothing to narrow
+		// FROM. Letting the request name one here would mint a token for an
+		// audience the user never saw.
+		throw new OAuthError(
+			"invalid_target",
+			"this grant is not bound to any resource",
+		);
+	}
+	const outside = requested.filter((value) => !granted.includes(value));
+	if (outside.length > 0) {
+		throw new OAuthError(
+			"invalid_target",
+			`this grant does not cover ${outside.join(", ")}`,
+		);
+	}
+	return [...requested];
+}
+
+/**
+ * Is this token for me?
+ *
+ * What a resource server asks. A token bound to nothing is accepted — that is
+ * every token issued before a client started sending `resource`, and refusing
+ * them would break each one. A token bound to SOMETHING must name this
+ * resource, or it was minted for another server and arriving here means it
+ * travelled.
+ */
+export function audienceAllows(
+	audience: readonly string[] | undefined,
+	resource: string | undefined,
+): boolean {
+	if (audience === undefined || audience.length === 0) return true;
+	if (resource === undefined) return true;
+	return audience.includes(resource);
+}

package/src/store.ts

@@ -51,6 +51,35 @@ export interface VisaStore {
 	findConsent(userId: string, clientId: string): Promise<Consent | null>;
 	saveConsent(consent: Consent): Promise<void>;
 
+	/**
+	 * Everything this user has granted, so they can be shown it.
+	 *
+	 * The consent is the unit a person manages: they authorised an
+	 * application, not a token. Tokens come and go under that decision.
+	 */
+	listConsents(userId: string): Promise<Consent[]>;
+
+	/**
+	 * Every access token of this user, EXPIRED ONES INCLUDED.
+	 *
+	 * Included deliberately: "last used" is most interesting precisely when
+	 * nothing is live any more, and a screen that hid them would tell a user an
+	 * application never touched their data when it did.
+	 */
+	listAccessTokens(userId: string): Promise<AccessToken[]>;
+
+	/**
+	 * Cut one application off for one user: every token, both kinds.
+	 *
+	 * Not the consent — {@link deleteConsent} is separate, because forgetting
+	 * the grant and ending the sessions are two different things and a caller
+	 * revoking in a panic wants the second one first.
+	 */
+	revokeAccessFor(userId: string, clientId: string, at: Date): Promise<void>;
+
+	/** Forget the grant, so the user is asked again next time. */
+	deleteConsent(userId: string, clientId: string): Promise<void>;
+
 	/**
 	 * Record that an access token was just used.
 	 *

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

@@ -57,6 +57,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 +83,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 +118,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 +130,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 +179,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");