From 77ba8a2aa0e628c2a1c944286aa3f73737f6c1aa Mon Sep 17 00:00:00 2001 From: Vensin Date: Tue, 3 Nov 2026 10:53:21 +0100 Subject: [PATCH] feat(auth): mark undemonstrable statuses as untested --- package-lock.json | 2 +- packages/auth/CHANGELOG.md | 8 ++++++++ packages/auth/lib/plugin.js | 11 +++++++++++ packages/auth/package.json | 2 +- packages/auth/test/plugin-docs.test.ts | 21 +++++++++++++++++++++ 5 files changed, 42 insertions(+), 2 deletions(-) diff --git a/package-lock.json b/package-lock.json index 1eab9ec..425910e 100644 --- a/package-lock.json +++ b/package-lock.json @@ -2647,7 +2647,7 @@ }, "packages/auth": { "name": "@inkanjs/auth", - "version": "0.2.0", + "version": "0.2.1", "license": "MIT", "devDependencies": { "@vxnsin/inkan": "^0.8.0" diff --git a/packages/auth/CHANGELOG.md b/packages/auth/CHANGELOG.md index cfc268b..02895d7 100644 --- a/packages/auth/CHANGELOG.md +++ b/packages/auth/CHANGELOG.md @@ -1,5 +1,13 @@ # Changelog +## 0.2.1 (unreleased) + +- The generated routes mark the statuses no example can show as `untested`, with the reason + (inkan 0.9's experimental `RouteSpec.untested`): 403, 429 and 503 on `POST /auth/login`, + 403 on `POST /auth/logout`, 429 and 503 on `POST /auth/token`, and 403, 409 and 429 on the + TOTP routes. An app with the plugin passes `inkan check --strict` without an + `export const untested` of its own. Older cores ignore the field. + ## 0.2.0 - **Any inkan `Store`** (inkan 0.8) for `store` and `bruteForce.store`: `memoryStore()` from diff --git a/packages/auth/lib/plugin.js b/packages/auth/lib/plugin.js index 09c5b15..8289138 100644 --- a/packages/auth/lib/plugin.js +++ b/packages/auth/lib/plugin.js @@ -901,6 +901,11 @@ function install(app, c) { const userSchemes = [...(session ? [c.sessionScheme] : []), ...(c.jwt ? ["bearer"] : [])]; const unknownLogin = { name: "an unknown login", body: { login: "nobody@example.com", password: "not-the-password" }, status: 401, expect: { type: "invalid-credentials" } }; const noCredentials = { name: "without credentials", status: 401, expect: { type: "unauthorized" } }; + // Statuses no example can show, with the reason: `inkan check --strict` lets them be + // (RouteSpec.untested, inkan 0.9, experimental). Older cores ignore the field. + const lockout = "a lockout after many failed logins"; + const tooBusy = "too many password checks at once"; + const reauth = "a login older than totp.reauth, or a wrong password"; // With an example account, inkan check logs in and goes on with the session cookie in its jar. const loggedIn = "a known login"; const afterLogin = session && c.example && fn(users.find) ? `POST ${app.prefix}${base}/login > ${loggedIn}` : undefined; @@ -921,6 +926,7 @@ function install(app, c) { response: { 200: t.object({ user: c.userSchema }), 401: P, 403: P, 429: P, 503: P }, meta: { [SETS_SESSION]: true }, examples: loginExamples, + untested: { 403: "a login from another site", 429: lockout, 503: tooBusy }, }, async (ctx) => { const user = await passwordLogin(ctx, ctx.body); @@ -940,6 +946,7 @@ function install(app, c) { body: t.object({ refreshToken: t.string().max(512).optional() }).optional(), response: { 204: t.empty(), 403: P }, examples: [{ name: "without a session", status: 204 }, ...afterLoginExample(204, { "sec-fetch-site": "same-origin" })], + untested: { 403: "a logout from another site" }, }, async (ctx) => { if (ctx.body?.refreshToken && c.issue) await revokeRefresh(ctx.body.refreshToken); @@ -973,6 +980,7 @@ function install(app, c) { body: loginBody, response: { 200: tokens, 401: P, 429: P, 503: P }, examples: [unknownLogin], + untested: { 429: lockout, 503: tooBusy }, }, async (ctx) => issueTokens(await passwordLogin(ctx, ctx.body)), ); @@ -1007,6 +1015,7 @@ function install(app, c) { body: t.object({ password: password.optional() }).optional(), response: { 200: t.object({ secret: t.string(), otpauthUrl: t.string() }), 401: P, 403: P, 409: P, 429: P }, examples: [noCredentials], + untested: { 403: reauth, 409: "an account with TOTP on already", 429: lockout }, }, async (ctx) => { const user = stateOf(ctx).user; @@ -1029,6 +1038,7 @@ function install(app, c) { body: t.object({ code: t.string().min(6).max(10), password: password.optional() }), response: { 200: t.object({ recoveryCodes: t.array(t.string()) }), 400: P, 401: P, 403: P, 409: P, 429: P }, examples: [{ ...noCredentials, body: { code: "123456" } }], + untested: { 403: reauth, 409: "TOTP on already, or no setup going on", 429: lockout }, }, async (ctx) => { const user = stateOf(ctx).user; @@ -1056,6 +1066,7 @@ function install(app, c) { body: t.object({ code: t.string().min(6).max(32), password: password.optional() }), response: { 204: t.empty(), 400: P, 401: P, 403: P, 409: P, 429: P }, examples: [{ ...noCredentials, body: { code: "123456" } }], + untested: { 403: reauth, 409: "an account without TOTP", 429: lockout }, }, async (ctx) => { const user = stateOf(ctx).user; diff --git a/packages/auth/package.json b/packages/auth/package.json index 58aa551..b6c5fe3 100644 --- a/packages/auth/package.json +++ b/packages/auth/package.json @@ -1,6 +1,6 @@ { "name": "@inkanjs/auth", - "version": "0.2.0", + "version": "0.2.1", "description": "Authentication for inkan without dependencies: sessions, JWTs, API keys, passwords, TOTP and OAuth on node:crypto alone.", "type": "module", "license": "MIT", diff --git a/packages/auth/test/plugin-docs.test.ts b/packages/auth/test/plugin-docs.test.ts index 9e970bf..6fb5981 100644 --- a/packages/auth/test/plugin-docs.test.ts +++ b/packages/auth/test/plugin-docs.test.ts @@ -105,3 +105,24 @@ test("inkan check with an example account: logs in, then /me and /logout with th assert.ok(failed.includes("POST /auth/login > a known login"), failed.join(", ")); assert.throws(() => auth({ secret: SECRET, users: makeUsers().source, example: { login: "x" } as never }), /example needs/); }); + +// RouteSpec.untested came with inkan 0.9; an older core ignores it, and its report has no +// `untested`. This test needs the 0.9 core and is skipped on 0.8. +test("inkan check --strict: the app of `inkan create app --auth` passes without an untested list", async (t) => { + for (const prefix of ["", "/api"]) { + const users = makeUsers(); + const plugin = auth({ + secret: SECRET, + users: { find: users.source.find, byId: users.source.byId }, + password: FAST, + example: { login: "bob@example.com", password: "correct horse" }, + }); + const app = inkan({ log: false }).register(plugin, {}, { prefix }); + const report = await app.check({ strict: true }); + if (!("untested" in report)) return t.skip("needs inkan 0.9 (RouteSpec.untested)"); + assert.ok(report.ok, JSON.stringify({ failed: report.results.filter((r) => !r.ok), uncovered: report.uncovered })); + assert.deepEqual(report.uncovered, []); + const onPurpose = (report as { untested: { method: string; path: string; status: number }[] }).untested.map((u) => `${u.method} ${u.path} ${u.status}`); + assert.deepEqual(onPurpose.sort(), [`POST ${prefix}/auth/login 403`, `POST ${prefix}/auth/login 429`, `POST ${prefix}/auth/login 503`, `POST ${prefix}/auth/logout 403`]); + } +});