@c9up/visa 0.1.2 → 0.1.4

package/src/VisaProvider.ts

@@ -14,6 +14,10 @@
  * decision; the page around it is yours. The README shows the ten lines.
  *
  * Duck-typed throughout: visa must not import its host's HTTP types.
+ *
+ * NAMED DEVIATION from the usual `request.all()`: these endpoints read the
+ * body only, and refuse a request that puts an OAuth parameter in the query
+ * string — see `readBody`.
  */
 
 import "./augmentations.js";
@@ -44,7 +48,10 @@ export interface VisaAppContext {
 interface VisaHttpContext {
 	request: {
 		header(name: string): string | undefined;
-		all(): Record<string, unknown>;
+		/** The parsed body — the only place an OAuth parameter is read from. */
+		body(): unknown;
+		/** Read only to refuse a request that put parameters in the URL. */
+		qs(): Record<string, unknown>;
 	};
 	response: {
 		status(code: number): unknown;
@@ -96,7 +103,7 @@ export default class VisaProvider {
 
 		router.post(`${prefix}/token`, async (ctx) => {
 			await this.#answer(ctx, async () => {
-				const body = ctx.request.all();
+				const body = readBody(ctx);
 				const credentials = manager.readCredentials({
 					body,
 					...readAuthorization(ctx),
@@ -113,7 +120,7 @@ export default class VisaProvider {
 
 		router.post(`${prefix}/introspect`, async (ctx) => {
 			await this.#answer(ctx, async () => {
-				const body = ctx.request.all();
+				const body = readBody(ctx);
 				const credentials = manager.readCredentials({
 					body,
 					...readAuthorization(ctx),
@@ -125,7 +132,7 @@ export default class VisaProvider {
 
 		router.post(`${prefix}/revoke`, async (ctx) => {
 			await this.#answer(ctx, async () => {
-				const body = ctx.request.all();
+				const body = readBody(ctx);
 				const credentials = manager.readCredentials({
 					body,
 					...readAuthorization(ctx),
@@ -144,7 +151,10 @@ export default class VisaProvider {
 			router.post(`${prefix}/register`, async (ctx) => {
 				await this.#answer(ctx, async () => {
 					const bearer = readBearer(ctx);
-					const created = await manager.register(ctx.request.all(), bearer);
+					const created = await manager.register(
+						readBody(ctx, REGISTRATION_PARAMETERS),
+						bearer,
+					);
 					// §3.2.1: 201, and the body carries a secret — no cache may
 					// keep it.
 					ctx.response.status(201);
@@ -245,12 +255,104 @@ export default class VisaProvider {
 	}
 }
 
+/**
+ * What may never travel in the URL of these endpoints.
+ *
+ * Every credential and every parameter the spec defines for them: the client's
+ * own (§2.3.1, RFC 7523), each grant's (§4), introspection's and revocation's
+ * (RFC 7662 §2.1, RFC 7009 §2.1), resource indicators (RFC 8707), a bearer
+ * token in its RFC 6750 §2.3 form, and the removed password grant's — a
+ * client still sending those sends a password.
+ */
+const OAUTH_PARAMETERS: ReadonlySet<string> = new Set([
+	"client_id",
+	"client_secret",
+	"client_assertion",
+	"client_assertion_type",
+	"grant_type",
+	"code",
+	"code_verifier",
+	"redirect_uri",
+	"refresh_token",
+	"scope",
+	"resource",
+	"token",
+	"token_type_hint",
+	"access_token",
+	"username",
+	"password",
+]);
+
+/** The same, plus the client metadata a registration carries (RFC 7591 §2). */
+const REGISTRATION_PARAMETERS: ReadonlySet<string> = new Set([
+	...OAUTH_PARAMETERS,
+	"redirect_uris",
+	"token_endpoint_auth_method",
+	"grant_types",
+	"response_types",
+	"client_name",
+	"client_uri",
+	"logo_uri",
+	"contacts",
+	"tos_uri",
+	"policy_uri",
+	"jwks_uri",
+	"jwks",
+	"software_id",
+	"software_version",
+	"software_statement",
+]);
+
+/**
+ * The parameters of a machine endpoint, read from the body and nowhere else.
+ *
+ * Every one of these requests carries a credential — a client secret, a code,
+ * a refresh or access token. RFC 6749 §2.3.1 says client credentials "MUST NOT
+ * be included in the request URI", and §3.2, RFC 7009 §2.1, RFC 7662 §2.1 and
+ * RFC 7591 §3.1 all define the parameters as a POST body. A URL is kept by
+ * access logs, proxies and traces where a body is not.
+ *
+ * So the query string is never read, and a request that puts an OAuth
+ * parameter there is refused rather than answered: accepting it would teach a
+ * client that the URL works, and the secret it carries is already in a log.
+ * Anything else in the query (a tracing or cache-busting parameter a proxy
+ * added) is ignored, not refused.
+ */
+function readBody(
+	ctx: VisaHttpContext,
+	forbidden: ReadonlySet<string> = OAUTH_PARAMETERS,
+): Record<string, unknown> {
+	const inUrl = Object.keys(ctx.request.qs()).filter((key) =>
+		forbidden.has(key),
+	);
+	if (inUrl.length > 0) {
+		throw new OAuthError(
+			"invalid_request",
+			`OAuth parameters go in the request body, never in the URL: ${inUrl.join(", ")}.`,
+		);
+	}
+	const body = ctx.request.body();
+	if (body === undefined || body === null) return {};
+	if (!isRecord(body)) {
+		throw new OAuthError(
+			"invalid_request",
+			"The request body must be a form or a JSON object.",
+		);
+	}
+	return body;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
 /** The initial access token a registration may carry (RFC 7591 §3). */
 function readBearer(ctx: VisaHttpContext): string | undefined {
 	const header = ctx.request.header("authorization");
 	if (header === undefined) return undefined;
 	const [scheme, value] = header.split(" ");
-	if (scheme?.toLowerCase() !== "bearer" || value === undefined)
+	// An empty value is no token at all, not a token that is the empty string.
+	if (scheme?.toLowerCase() !== "bearer" || value === undefined || value === "")
 		return undefined;
 	return value;
 }

package/src/clients.ts

@@ -157,6 +157,7 @@ function stringOrUndefined(value: unknown): string | undefined {
 export async function authenticateClient(
 	credentials: ClientCredentials,
 	load: (id: string) => Promise<Client | null>,
+	now: Date = new Date(),
 ): Promise<Client> {
 	if (credentials.clientId === undefined) {
 		throw new OAuthError("invalid_client", "Client authentication failed.");
@@ -192,6 +193,15 @@ export async function authenticateClient(
 	) {
 		throw new OAuthError("invalid_client", "Client authentication failed.");
 	}
+
+	// Registration may have answered `client_secret_expires_at`. This is where
+	// that answer becomes true: checked after the secret matched, so a wrong
+	// secret and an expired one are still the same sentence to the caller.
+	// Every endpoint that authenticates a client — token, introspection,
+	// revocation — arrives here, so one check covers all three.
+	if (client.secretExpiresAt !== undefined && client.secretExpiresAt <= now) {
+		throw new OAuthError("invalid_client", "Client authentication failed.");
+	}
 	return client;
 }
 

package/src/configure.ts

@@ -25,6 +25,17 @@ import { stubsRoot } from "./stubs.js";
  */
 const MIGRATION_STUB = "database/migrations/9000_create_visa_tables.stub";
 
+/**
+ * Columns added after the tables first shipped, one migration each.
+ *
+ * Written on every run: `makeUsingStub` leaves a file that already exists
+ * alone, so an application that configured an earlier version keeps its 9000
+ * and gains only what it is missing by running `ream configure` again.
+ */
+const UPGRADE_STUBS = [
+	"database/migrations/9001_add_visa_client_secret_expiry.stub",
+];
+
 interface Codemods {
 	addProvider(importPath: string): Promise<void>;
 	addEnvVars(vars: Record<string, string>): Promise<void>;
@@ -45,7 +56,9 @@ export async function configure(codemods: Codemods): Promise<void> {
 	// Fail fast BEFORE touching the project: a pruned tarball or an unreadable
 	// stub must not leave an application with a provider registered, a config
 	// written and no tables to put anything in.
-	await access(resolve(stubsRoot, MIGRATION_STUB), constants.R_OK);
+	for (const stub of [MIGRATION_STUB, ...UPGRADE_STUBS]) {
+		await access(resolve(stubsRoot, stub), constants.R_OK);
+	}
 
 	// The config below reads this, so it is declared here. Writing the file
 	// without it leaves an application whose config asks the environment for
@@ -60,4 +73,7 @@ export async function configure(codemods: Codemods): Promise<void> {
 	// data layer deletes the file and keeps its own store — which is why this
 	// is a migration and not a schema the package owns.
 	await codemods.makeUsingStub(stubsRoot, MIGRATION_STUB);
+	for (const stub of UPGRADE_STUBS) {
+		await codemods.makeUsingStub(stubsRoot, stub);
+	}
 }

package/src/guard.ts

@@ -9,7 +9,8 @@
  * upstream rule read off `@adonisjs/auth`'s build rather than recalled.
  *
  * Two things this fixes for every application at once. A route gate no longer
- * has to introspect the token itself — the scopes are on the guard's token. And
+ * has to introspect the token itself — the scopes are on the guard's token,
+ * and only there: `user.permissions` stays the user's own. And
  * the user is fetched through the application's own provider on every request,
  * so an account disabled after the token was issued is refused here instead of
  * in each application that remembers to check.
@@ -364,7 +365,17 @@ export class VisaGuard {
 	async verify(presented: string): Promise<GuardResult> {
 		const store = this.#store();
 		const now = new Date();
-		const verified = await verifyAccessToken(presented, store, now);
+		// The resource this guard declares is the resource it enforces. Passing
+		// it is the whole of RFC 8707 on this side: without it a token minted
+		// for another resource server — one the same authorization server also
+		// serves — is honoured here, and the `resource` advertised in the
+		// challenge is a claim nothing backs.
+		const verified = await verifyAccessToken(
+			presented,
+			store,
+			now,
+			this.#config.resource,
+		);
 		if (verified === null) {
 			return { authenticated: false, error: "Invalid or expired access token" };
 		}
@@ -400,19 +411,17 @@ export class VisaGuard {
 
 		// A copy: the provider's object is the application's, and a guard that
 		// mutated it would leak one request's token into the next.
+		//
+		// The scopes go on `currentAccessToken` and NOWHERE else — upstream's
+		// access-tokens guard leaves the user model untouched the same way. They
+		// are never merged into `permissions`: a scope is chosen by the client's
+		// registration and granted by consent, which never checks that the user
+		// holds a permission of the same name, so a merge would hand any user a
+		// route permission they lack the moment a scope is named like one
+		// (`orders:write`). And a token limited to `profile` must not carry the
+		// user's other rights to a third-party client either: the two axes meet
+		// only as an intersection, `permission && currentAccessToken.allows(...)`.
 		const user: GuardUser = { ...subject, currentAccessToken: token };
-		if (verified.scopes.length > 0) {
-			// Scopes surface on `permissions` as well, the way warden's access-token
-			// guard does it, so `ctx.auth.user.permissions` reads the same whichever
-			// guard authenticated.
-			//
-			// They remain a SEPARATE axis from the route-level rights gate, exactly
-			// as upstream: a token ability is checked with
-			// `currentAccessToken.allows(...)`, and Bouncer does not consult it.
-			user.permissions = [
-				...new Set([...(subject.permissions ?? []), ...verified.scopes]),
-			];
-		}
 		return { authenticated: true, user };
 	}
 }

package/src/index.ts

@@ -103,6 +103,7 @@ export type {
 } from "./types.js";
 export {
 	type AuthorizationOutcome,
+	type ConsentTicket,
 	type VisaConfig,
 	VisaManager,
 } from "./VisaManager.js";

package/src/register.ts

@@ -20,7 +20,8 @@
  * it decide what it may do.
  */
 
-import { OAuthError } from "./errors.js";
+import { hashMatches, sha256 } from "./crypto.js";
+import { OAuthError, VisaError } from "./errors.js";
 import type { Client, ClientAuthMethod, GrantType } from "./types.js";
 
 /** The metadata a request may send (§2). Unknown members are ignored. */
@@ -113,10 +114,16 @@ export function validateRegistration(
 		);
 	}
 	if (options.initialAccessToken !== undefined) {
-		// Constant-time is not the point here: the token is compared once per
-		// registration, and a registration endpoint is not a guessing oracle
-		// worth the machinery. Absent or wrong reads the same to the caller.
-		if (presentedToken !== options.initialAccessToken) {
+		// Constant time, like every other secret here. This one is a static,
+		// operator-chosen string — often shorter than a minted token — that an
+		// anonymous caller may test once per request, as often as they like.
+		// Both sides are hashed first so the comparison never depends on the
+		// configured length either. Absent or wrong reads the same to the caller.
+		if (
+			presentedToken === undefined ||
+			presentedToken === "" ||
+			!hashMatches(sha256(presentedToken), sha256(options.initialAccessToken))
+		) {
 			throw new OAuthError(
 				"invalid_client_metadata",
 				"Registration on this server needs an initial access token.",
@@ -163,7 +170,6 @@ export function registrationResponse(
 	client: Client,
 	issuedAt: Date,
 	secret: string | undefined,
-	options: RegistrationOptions,
 ): ClientRegistrationResponse {
 	const seconds = Math.floor(issuedAt.getTime() / 1000);
 	return {
@@ -172,13 +178,18 @@ export function registrationResponse(
 		client_id_issued_at: seconds,
 		// REQUIRED when a secret was issued, and `0` is the spelling for "never"
 		// — not an omission, which would mean the field was not answered.
+		//
+		// Read off the client rather than recomputed from the options: the
+		// answer and the stored expiry are then the same value by construction,
+		// and cannot drift into a server that announces an expiry it does not
+		// enforce.
 		...(secret === undefined
 			? {}
 			: {
 					client_secret_expires_at:
-						options.secretTtlSeconds === undefined
+						client.secretExpiresAt === undefined
 							? 0
-							: seconds + options.secretTtlSeconds,
+							: Math.floor(client.secretExpiresAt.getTime() / 1000),
 				}),
 		redirect_uris: client.redirectUris,
 		grant_types: client.grantTypes,
@@ -243,6 +254,31 @@ function assertRedirectUri(value: string): void {
 	);
 }
 
+/**
+ * When a secret issued now stops working, or `undefined` for never.
+ *
+ * The TTL is the deployment's value, not the client's, so a bad one is a
+ * configuration mistake and says so — `VisaError`, not an OAuth error the
+ * caller would read as their own fault. Refused rather than rounded: a
+ * fractional or negative TTL means someone intended something this cannot
+ * carry out, and a secret quietly issued already-expired (or never expiring)
+ * is the worse answer either way.
+ */
+export function secretExpiryFor(
+	issuedAt: Date,
+	ttlSeconds: number | undefined,
+): Date | undefined {
+	if (ttlSeconds === undefined) return undefined;
+	if (!Number.isInteger(ttlSeconds) || ttlSeconds <= 0) {
+		throw new VisaError(
+			"E_VISA_INVALID_SECRET_TTL",
+			`registration.secretTtlSeconds must be a positive whole number of seconds; received ${ttlSeconds}.`,
+			{ hint: "Leave it out for a secret that never expires." },
+		);
+	}
+	return new Date(issuedAt.getTime() + ttlSeconds * 1000);
+}
+
 function readStringList(value: unknown): string[] {
 	if (value === undefined || value === null) return [];
 	if (!Array.isArray(value)) {
@@ -251,7 +287,17 @@ function readStringList(value: unknown): string[] {
 			"redirect_uris and grant_types must be arrays of strings.",
 		);
 	}
-	return value.filter((entry): entry is string => typeof entry === "string");
+	// Refused, not filtered. Dropping the entries that are not strings answers
+	// 201 to a request nobody wrote: `["https://app/cb", 42]` registered one
+	// redirect uri while the client believed it had registered two, and the
+	// second one silently not working is found much later, by a user.
+	if (value.some((entry) => typeof entry !== "string")) {
+		throw new OAuthError(
+			"invalid_client_metadata",
+			"redirect_uris and grant_types must be arrays of strings.",
+		);
+	}
+	return [...value];
 }
 
 function readScope(value: unknown): string[] {

package/src/store.ts

@@ -20,6 +20,17 @@ import type {
 export interface VisaStore {
 	findClient(id: string): Promise<Client | null>;
 
+	/**
+	 * Persist a client — what `registerClient`, and so dynamic registration
+	 * (RFC 7591), writes through. Awaited: a 201 carrying a secret for a
+	 * client whose insert failed would hand out a credential nothing accepts.
+	 *
+	 * Optional, for a store whose clients live in a table another service
+	 * owns. Without it `registerClient` refuses, and a server with
+	 * registration turned on refuses to boot.
+	 */
+	saveClient?(client: Client): Promise<void>;
+
 	saveAuthorizationCode(code: AuthorizationCode): Promise<void>;
 	findAuthorizationCode(codeHash: string): Promise<AuthorizationCode | null>;
 	/**

package/src/stores/atlas.ts

@@ -166,10 +166,12 @@ export class AtlasStore implements VisaStore {
 		const row = await this.#db.from(this.#tables.clients).where({ id }).first();
 		if (row === null) return null;
 		const secretHash = optionalString(row.secret_hash);
+		const secretExpiresAt = decodeDate(row.secret_expires_at);
 		return {
 			id: requireString(row.id, "id"),
 			name: requireString(row.name, "name"),
 			...(secretHash === undefined ? {} : { secretHash }),
+			...(secretExpiresAt === undefined ? {} : { secretExpiresAt }),
 			redirectUris: decodeList(row.redirect_uris, "redirect_uris"),
 			grantTypes: decodeList(row.grant_types, "grant_types").filter(
 				isGrantType,
@@ -180,12 +182,15 @@ export class AtlasStore implements VisaStore {
 		};
 	}
 
-	/** Persist a registered client. Not on the contract — what `registerClient` writes through. */
+	/** Persist a registered client — 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,
+			// Without it an expiry announced at registration is never enforced:
+			// authentication reads it off the client and nowhere else.
+			secret_expires_at: client.secretExpiresAt ?? null,
 			redirect_uris: encodeList(client.redirectUris),
 			grant_types: encodeList(client.grantTypes),
 			scopes: encodeList(client.scopes),

package/src/stores/memory.ts

@@ -30,10 +30,8 @@ export class MemoryStore implements VisaStore {
 		for (const client of clients) this.#clients.set(client.id, client);
 	}
 
-	/** Register a client. Returns it, so a caller can keep the reference. */
-	addClient(client: Client): Client {
+	async saveClient(client: Client): Promise<void> {
 		this.#clients.set(client.id, client);
-		return client;
 	}
 
 	async findClient(id: string): Promise<Client | null> {

package/src/token.ts

@@ -224,6 +224,13 @@ async function exchangeRefresh(
 	const requested = asString(request.scope);
 	const scopes =
 		requested === undefined ? record.scopes : narrow(requested, record.scopes);
+	const resources = narrowResources(
+		validateResources(
+			readResourceParameter(request.resource),
+			options.resourcesSupported,
+		),
+		record.resources ?? [],
+	);
 
 	if (!(await store.consumeRefreshToken(record.tokenHash, now))) throw invalid;
 
@@ -233,13 +240,18 @@ async function exchangeRefresh(
 			...(record.userId === undefined ? {} : { userId: record.userId }),
 			scopes,
 			familyId: record.familyId,
-			resources: narrowResources(
-				validateResources(
-					readResourceParameter(request.resource),
-					options.resourcesSupported,
-				),
-				record.resources ?? [],
-			),
+			resources,
+			// Only the ACCESS token is narrowed. RFC 6749 §6: a rotated refresh
+			// token's scope "MUST be identical to that of the refresh token
+			// included by the client in the request" — otherwise asking for a
+			// down-scoped token for one call would cost the rest of the user's
+			// consent for the whole session. Resources follow the same rule:
+			// RFC 8707 has a client refresh once per resource it calls, which
+			// only works if a token for one leaves the others reachable.
+			refresh: {
+				scopes: record.scopes,
+				resources: record.resources ?? [],
+			},
 		},
 		store,
 		options,
@@ -306,6 +318,13 @@ interface Issued {
 	familyId?: string;
 	/** RFC 8707 — what the token is for. Empty means unbound. */
 	resources?: string[];
+	/**
+	 * What the refresh token carries, when it differs from the access token.
+	 *
+	 * Absent, the refresh token carries the access token's scopes and
+	 * resources — the case of a code exchange, where both halves are the grant.
+	 */
+	refresh?: { scopes: string[]; resources: string[] };
 }
 
 /** Mint the pair and store both, hashed. */
@@ -347,18 +366,18 @@ async function issue(
 	const refreshTtl =
 		options.refreshTokenTtlSeconds ?? DEFAULTS.refreshTokenTtlSeconds;
 	const refreshToken = randomToken();
+	const refreshScopes = grant.refresh?.scopes ?? grant.scopes;
+	const refreshResources = grant.refresh?.resources ?? grant.resources ?? [];
 	await store.saveRefreshToken({
 		tokenHash: hashSecret(refreshToken),
 		familyId: grant.familyId,
 		clientId: grant.client.id,
 		...(grant.userId === undefined ? {} : { userId: grant.userId }),
-		scopes: grant.scopes,
+		scopes: refreshScopes,
 		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 }),
+		...(refreshResources.length === 0 ? {} : { resources: refreshResources }),
 	});
 	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. */

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

@@ -26,6 +26,8 @@ export default class CreateVisaTables extends Migration {
 			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();
+			// `secret_expires_at` is added by 9001, so a table created before it
+			// existed gets it the same way a new one does.
 			t.json("redirect_uris").notNullable();
 			t.json("grant_types").notNullable();
 			t.json("scopes").notNullable();

package/stubs/database/migrations/9001_add_visa_client_secret_expiry.stub

@@ -0,0 +1,29 @@
+---
+to: database/migrations/9001_add_visa_client_secret_expiry.ts
+---
+import { Migration } from "@c9up/atlas";
+
+/**
+ * When a client's secret stops working (RFC 7591 §3.2.1).
+ *
+ * Its own migration rather than a line in 9000, so an application whose
+ * tables already exist gets the column by running `ream configure @c9up/visa`
+ * again: 9000 is already there and is left alone, this one lands and adds it.
+ *
+ * Null means the secret does not expire. The store reads it at every client
+ * authentication: an expiry announced at registration and not stored here
+ * would never be enforced.
+ */
+export default class AddVisaClientSecretExpiry extends Migration {
+	async up() {
+		this.schema.alterTable("visa_clients", (t) => {
+			t.timestamp("secret_expires_at").nullable();
+		});
+	}
+
+	async down() {
+		this.schema.alterTable("visa_clients", (t) => {
+			t.dropColumn("secret_expires_at");
+		});
+	}
+}