@things-factory/auth-base 10.1.31 → 10.1.33

package/tests/checkin-privilege-seam-db.test.ts

@@ -0,0 +1,158 @@
+import { closeAuthDatabase, Domain, getRepository, openAuthDatabase, resetAuthDatabase } from './db'
+import { loadCompiled } from './compiled'
+
+const { Privilege } = loadCompiled('service/privilege/privilege')
+const { Role } = loadCompiled('service/role/role')
+const { User, UserStatus } = loadCompiled('service/user/user')
+const { canUserCheckinDomain } = loadCompiled('utils/can-user-checkin-domain')
+
+/**
+ * The seam between "may this person come in" and "may this person do that".
+ *
+ * ── The two rules are not the same rule ─────────────────────────────────────
+ * Coming in (`checkin-domain-rule.ts`) asks for **membership AND a role**, or a partner grant,
+ * or ownership. The membership half is load-bearing and the file says why: a role defined in a
+ * parent domain is inherited by every child, so "holds a parent role" on its own would make a
+ * role granted for one child an entry pass to all its siblings.
+ *
+ * Acting (`User.hasPrivilege`) asks only for a role in this domain or its parent. There is no
+ * membership condition. That is on purpose and written down — the comment above it delegates
+ * the sibling problem to the checkin gate.
+ *
+ * ── So what does this file do ───────────────────────────────────────────────
+ * It writes down the one line where the two answers differ, which the specs never had:
+ *
+ *   not a member + holds a parent role      checkin ✗      privilege ○
+ *
+ * `spec/unit/checkin-privilege.spec.ts` opens by talking about "a user who checked in to a
+ * child domain", and then every one of its ten fixtures makes that user a member — the variable
+ * is even called `member`. The premise it names is never the thing it varies, so the gap sits
+ * outside all of it.
+ *
+ * ── Why this is pinned green rather than written red ────────────────────────
+ * Both halves are what the code does today, and today it does not leak: every server caller of
+ * `hasPrivilege` sits behind `domainAuthenticateMiddleware`, which runs the checkin gate first
+ * (measured 2026-09-20 across all nineteen call sites — board-service and figure-service routers
+ * are on `domainPrivateRouter`, the rest arrive through GraphQL or the subscription middleware).
+ *
+ * So this is one layer of depth, not an open door. A red test would mean a broken build for a
+ * decision nobody has taken yet. What this does instead is make the gap impossible to close or
+ * widen without saying so: **when the privilege layer gains the membership condition, the second
+ * assertion here flips**, and that is the axis the fix splits.
+ *
+ * ⚠ sqlite (`tests/db.ts`).
+ */
+
+let parent: any
+let child: any
+let sibling: any
+let outsider: any
+
+/** `context.state.domain` carries `parentId`; the repository does not fill it in. */
+async function withParentId(domain: any, parentId: string | null) {
+  return { ...(await getRepository(Domain).findOneBy({ id: domain.id })), parentId }
+}
+
+beforeAll(async () => {
+  await openAuthDatabase()
+})
+
+afterAll(async () => {
+  await closeAuthDatabase()
+})
+
+beforeEach(async () => {
+  await resetAuthDatabase()
+
+  const p = await getRepository(Domain).save({ name: 'system', subdomain: 'system' })
+  const c = await getRepository(Domain).save({ name: 'acme', subdomain: 'acme', parent: p })
+  const s = await getRepository(Domain).save({ name: 'beta', subdomain: 'beta', parent: p })
+  const o = await getRepository(Domain).save({ name: 'gamma', subdomain: 'gamma' })
+
+  parent = await withParentId(p, null)
+  child = await withParentId(c, p.id)
+  sibling = await withParentId(s, p.id)
+  outsider = await withParentId(o, null)
+})
+
+async function inheritedRoleHolder(memberOf: any[]) {
+  const seeing = await getRepository(Privilege).save({ name: 'query', category: 'board' })
+  const role = await getRepository(Role).save({
+    name: 'viewer',
+    domain: { id: parent.id },
+    privileges: [seeing]
+  })
+
+  const person = await getRepository(User).save({
+    username: 'kim@acme.z',
+    email: 'kim@acme.z',
+    name: 'kim',
+    status: UserStatus.ACTIVATED,
+    domains: memberOf.map(domain => ({ id: domain.id })),
+    roles: [role]
+  })
+
+  return await getRepository(User).findOne({ where: { id: person.id }, relations: ['domains', 'roles'] })
+}
+
+describe('a member of this domain holding an inherited role', () => {
+  it('comes in, and may act', async () => {
+    /* The case the inheritance exists for, and the one the specs cover ten times over. */
+    const person = await inheritedRoleHolder([child])
+
+    expect(await canUserCheckinDomain(person, child)).toBe(true)
+    expect(await User.hasPrivilege('query', 'board', child, person)).toBe(true)
+  })
+})
+
+describe('⚠ someone who is not a member but holds the parent role', () => {
+  it('does not come in', async () => {
+    /*
+     * The membership half doing its job. Without it, a role granted inside one child would be
+     * an entry pass to every sibling of that child.
+     */
+    const person = await inheritedRoleHolder([sibling])
+
+    expect(await canUserCheckinDomain(person, child)).toBe(false)
+  })
+
+  it('⚠ but would be allowed to act, if anything asked', async () => {
+    /*
+     * ⚠ **This is the gap, written down.** The privilege layer does not ask about membership, so
+     * it answers yes for a person the door would have turned away.
+     *
+     * It costs nothing today because nothing reaches `hasPrivilege` without the door having run
+     * first. It is one layer rather than two, and this line is what a second layer would change.
+     */
+    const person = await inheritedRoleHolder([sibling])
+
+    expect(await User.hasPrivilege('query', 'board', child, person)).toBe(true)
+  })
+
+  it('holds for someone with no membership at all', async () => {
+    /* Not an artefact of being a member of a sibling — belonging nowhere reads the same. */
+    const person = await inheritedRoleHolder([])
+
+    expect(await canUserCheckinDomain(person, child)).toBe(false)
+    expect(await User.hasPrivilege('query', 'board', child, person)).toBe(true)
+  })
+})
+
+describe('what the gap does not extend to', () => {
+  it('a domain that is not below the role domain', async () => {
+    /*
+     * The privilege layer is loose about membership, not about inheritance. A role defined in
+     * `system` reaches `system` and its children, and `gamma` is neither.
+     */
+    const person = await inheritedRoleHolder([outsider])
+
+    expect(await canUserCheckinDomain(person, outsider)).toBe(false)
+    expect(await User.hasPrivilege('query', 'board', outsider, person)).toBe(false)
+  })
+
+  it('a privilege the role does not carry', async () => {
+    const person = await inheritedRoleHolder([sibling])
+
+    expect(await User.hasPrivilege('mutation', 'board', child, person)).toBe(false)
+  })
+})

package/tests/credential-at-rest-db.test.ts

@@ -0,0 +1,246 @@
+import { config } from '@things-factory/env'
+
+import { closeAuthDatabase, Domain, getRepository, openAuthDatabase, resetAuthDatabase } from './db'
+import { loadCompiled } from './compiled'
+
+const { Appliance } = loadCompiled('service/appliance/appliance')
+const { Application } = loadCompiled('service/application/application')
+const { User, UserStatus } = loadCompiled('service/user/user')
+
+/**
+ * Storing a credential as ciphertext, on the installations that asked for it (ADR-0085).
+ *
+ * ── The three states that have to hold ──────────────────────────────────────
+ *
+ *   off            writes plaintext, reads plaintext        an untouched deployment
+ *   on             writes ciphertext, reads either          the rows convert one at a time
+ *   on then off    writes plaintext again, reads either     turning it off loses nothing
+ *
+ * The third is the one that makes the switch safe to try. If reading followed the switch, a
+ * deployment that turned it on and then changed its mind would lose every row written while it
+ * was on — the values would still be in the table and would read as nothing.
+ *
+ * These go through the repository rather than calling the transformer, so what is checked is
+ * what a column actually does. The raw column is read with a second query that bypasses the
+ * entity, which is the only way to see which shape is on disk.
+ *
+ * ⚠ sqlite (`tests/db.ts`).
+ */
+
+/** What `shell`'s transformer writes: 32 hex characters of IV, a colon, then hex. */
+const CIPHERTEXT = /^[0-9a-f]{32}:(?:[0-9a-f]{2})+$/
+
+const configGet = config.get
+
+function encryptionOff() {
+  config.get = configGet
+}
+
+function encryptionOn() {
+  config.get = ((key: string, fallback?: any) =>
+    key === 'credential/encryptAtRest' ? true : configGet(key, fallback)) as typeof config.get
+}
+
+let domain: any
+
+/** The bytes on disk, read without the entity so the transformer does not run. */
+async function storedAccessToken(id: string): Promise<string> {
+  const [row] = await getRepository(Appliance).query('select access_token from appliances where id = ?', [id])
+
+  return row?.access_token
+}
+
+async function storedAppSecret(id: string): Promise<string> {
+  const [row] = await getRepository(Application).query('select app_secret from applications where id = ?', [id])
+
+  return row?.app_secret
+}
+
+/** Application declares six columns non-null; only appSecret matters here. */
+async function saveApplication(appSecret: string) {
+  return await getRepository(Application).save({
+    domain,
+    name: 'billing',
+    email: 'billing@acme.z',
+    url: 'https://billing.example.com',
+    redirectUrl: 'https://billing.example.com/callback',
+    status: 0,
+    type: 'OTHERS',
+    appSecret
+  })
+}
+
+async function saveAppliance(name: string, accessToken: string) {
+  return await getRepository(Appliance).save({
+    domain,
+    name,
+    serialNo: `${name}-SN`,
+    brand: 'Acme',
+    model: 'X1',
+    accessToken
+  })
+}
+
+beforeAll(async () => {
+  await openAuthDatabase()
+})
+
+afterAll(async () => {
+  encryptionOff()
+  await closeAuthDatabase()
+})
+
+beforeEach(async () => {
+  encryptionOff()
+  await resetAuthDatabase()
+
+  domain = await getRepository(Domain).save({ name: 'acme', subdomain: 'acme' })
+})
+
+describe('with the switch off — an installation that configured nothing', () => {
+  it('stores the token as it always did', async () => {
+    const saved = await saveAppliance('gate-a', 'plain-token-value')
+
+    expect(await storedAccessToken(saved.id)).toEqual('plain-token-value')
+  })
+
+  it('reads back what it wrote', async () => {
+    const saved = await saveAppliance('gate-b', 'plain-token-value')
+
+    expect((await getRepository(Appliance).findOneBy({ id: saved.id })).accessToken).toEqual('plain-token-value')
+  })
+
+  it('stores an application secret as it always did', async () => {
+    const saved = await saveApplication('plain-secret')
+
+    expect(await storedAppSecret(saved.id)).toEqual('plain-secret')
+    expect((await getRepository(Application).findOneBy({ id: saved.id })).appSecret).toEqual('plain-secret')
+  })
+})
+
+describe('with the switch on', () => {
+  beforeEach(() => encryptionOn())
+
+  it('stores the token as ciphertext', async () => {
+    const saved = await saveAppliance('gate-c', 'secret-token-value')
+    const onDisk = await storedAccessToken(saved.id)
+
+    expect(onDisk).toMatch(CIPHERTEXT)
+    expect(onDisk).not.toContain('secret-token-value')
+  })
+
+  it('reads it back as what was written', async () => {
+    const saved = await saveAppliance('gate-d', 'secret-token-value')
+
+    expect((await getRepository(Appliance).findOneBy({ id: saved.id })).accessToken).toEqual('secret-token-value')
+  })
+
+  it('stores an application secret as ciphertext', async () => {
+    const saved = await saveApplication('secret-value')
+
+    expect(await storedAppSecret(saved.id)).toMatch(CIPHERTEXT)
+    expect((await getRepository(Application).findOneBy({ id: saved.id })).appSecret).toEqual('secret-value')
+  })
+
+  it('does not make two rows with the same secret look the same at rest', async () => {
+    /* The IV is per write. Without it, matching rows would say which appliances share a token. */
+    const a = await saveAppliance('gate-e', 'same-token')
+    const b = await saveAppliance('gate-f', 'same-token')
+
+    expect(await storedAccessToken(a.id)).not.toEqual(await storedAccessToken(b.id))
+  })
+})
+
+describe('turning it on over rows that are already there', () => {
+  it('still reads a row written before the switch', async () => {
+    /*
+     * ⚠ The case that lets the switch be turned on at all. Every row in the table is plaintext
+     * on the day it goes on. If reading them answered nothing, the credentials would vanish from
+     * the screens while sitting in the table.
+     */
+    const saved = await saveAppliance('gate-g', 'written-before')
+
+    encryptionOn()
+
+    expect((await getRepository(Appliance).findOneBy({ id: saved.id })).accessToken).toEqual('written-before')
+    expect(await storedAccessToken(saved.id)).toEqual('written-before')
+  })
+
+  it('converts that row the next time it is written', async () => {
+    /* One row at a time, as each is touched. There is no pass over the table. */
+    const saved = await saveAppliance('gate-h', 'written-before')
+
+    encryptionOn()
+    await getRepository(Appliance).save({ ...saved, accessToken: 'written-after' })
+
+    expect(await storedAccessToken(saved.id)).toMatch(CIPHERTEXT)
+    expect((await getRepository(Appliance).findOneBy({ id: saved.id })).accessToken).toEqual('written-after')
+  })
+
+  it('leaves untouched rows alone', async () => {
+    const converted = await saveAppliance('gate-i', 'one')
+    const untouched = await saveAppliance('gate-j', 'two')
+
+    encryptionOn()
+    await getRepository(Appliance).save({ ...converted, accessToken: 'one-again' })
+
+    expect(await storedAccessToken(converted.id)).toMatch(CIPHERTEXT)
+    expect(await storedAccessToken(untouched.id)).toEqual('two')
+
+    /* And both still read. That is the state a half-converted installation is in. */
+    expect((await getRepository(Appliance).findOneBy({ id: converted.id })).accessToken).toEqual('one-again')
+    expect((await getRepository(Appliance).findOneBy({ id: untouched.id })).accessToken).toEqual('two')
+  })
+})
+
+describe('turning it off after it has been on', () => {
+  it('keeps reading the rows written while it was on', async () => {
+    /*
+     * ⚠ What makes the switch safe to try. The switch governs writing only — if it governed
+     * reading, turning it off would strand every row written while it was on.
+     */
+    encryptionOn()
+    const saved = await saveAppliance('gate-k', 'written-while-on')
+
+    expect(await storedAccessToken(saved.id)).toMatch(CIPHERTEXT)
+
+    encryptionOff()
+
+    expect((await getRepository(Appliance).findOneBy({ id: saved.id })).accessToken).toEqual('written-while-on')
+  })
+
+  it('writes plaintext again from then on', async () => {
+    encryptionOn()
+    const saved = await saveAppliance('gate-l', 'written-while-on')
+
+    encryptionOff()
+    await getRepository(Appliance).save({ ...saved, accessToken: 'written-while-off' })
+
+    expect(await storedAccessToken(saved.id)).toEqual('written-while-off')
+  })
+})
+
+describe('what this does not touch', () => {
+  it('leaves User.password alone', async () => {
+    /*
+     * ⚠ Deliberate, and the reason is in `credential-at-rest.ts`. That column holds an HMAC for a
+     * person and a token for a machine, and a column transformer cannot tell them apart.
+     * Encrypting everybody's password hash to reach the machines' tokens is the wrong trade; the
+     * machine credential needs a column of its own (§8 step 4).
+     */
+    encryptionOn()
+
+    const user = await getRepository(User).save({
+      username: 'operator@acme.z',
+      email: 'operator@acme.z',
+      name: 'operator',
+      status: UserStatus.ACTIVATED,
+      password: 'hashed-value',
+      domains: [domain]
+    })
+
+    const [row] = await getRepository(User).query('select password from users where id = ?', [user.id])
+
+    expect(row.password).toEqual('hashed-value')
+  })
+})

package/tests/credential-features-off-db.test.ts

@@ -0,0 +1,189 @@
+import { config } from '@things-factory/env'
+
+import { closeAuthDatabase, Domain, getRepository, openAuthDatabase, resetAuthDatabase } from './db'
+import { loadCompiled } from './compiled'
+
+const jwt = require('jsonwebtoken')
+
+const { User, UserStatus } = loadCompiled('service/user/user')
+const { ApplianceMutation } = loadCompiled('service/appliance/appliance-mutation')
+
+const mutation = new ApplianceMutation()
+
+/**
+ * What an installation that configures nothing sees (ADR-0085 decisions 1 and 2).
+ *
+ * ── Why this file exists ────────────────────────────────────────────────────
+ * An appliance token lives a year, and the ones in the field were issued by the version running
+ * now. The whole design rests on one claim: **taking this release changes nothing until the
+ * installation asks for it.** That claim is easy to state and easy to break — a door that
+ * forgets its switch, a serial that starts filling in on its own — so it is held here rather
+ * than in prose.
+ *
+ * These cases run with no config set at all, which is what `config.get(key, false)` sees in a
+ * deployment whose config file was never touched.
+ *
+ * `appliance-revoke-db.test.ts` holds the other side: what the features do once they are on.
+ */
+
+let domain: any
+let actor: any
+
+function context(d: any = domain) {
+  return {
+    state: { domain: d, user: actor, tx: undefined },
+    throw: (code: number, message: string) => {
+      const error: any = new Error(message)
+      error.status = code
+      throw error
+    }
+  } as any
+}
+
+async function shadowUserOf(applianceId: string) {
+  return await getRepository(User).findOneBy({ reference: applianceId, userType: 'appliance' })
+}
+
+beforeAll(async () => {
+  await openAuthDatabase()
+})
+
+afterAll(async () => {
+  await closeAuthDatabase()
+})
+
+beforeEach(async () => {
+  await resetAuthDatabase()
+
+  domain = await getRepository(Domain).save({ name: 'acme', subdomain: 'acme' })
+  actor = await getRepository(User).save({
+    username: 'operator@acme.z',
+    email: 'operator@acme.z',
+    name: 'operator',
+    status: UserStatus.ACTIVATED,
+    domains: [domain]
+  })
+})
+
+describe('an installation that configures neither feature', () => {
+  it('reads both switches as off', () => {
+    /*
+     * The mechanism the rest of this file depends on. `config.get` answers the default when the
+     * key is absent, so "never configured" and "off" are one thing.
+     */
+    expect(config.get('credential/encryptAtRest', false)).toBeFalsy()
+    expect(config.get('credential/revocable', false)).toBeFalsy()
+  })
+
+  it('has no revocation door', async () => {
+    /*
+     * ⚠ The case the switch exists for. `revokeApplianceCredential` shipped before this design
+     * and went out without a switch; it belongs behind one now, and an installation that never
+     * asked for it must not find it.
+     */
+    const appliance = await mutation.createAppliance(
+      { name: 'gate-a', serialNo: 'SN-A', brand: 'Acme', model: 'X1' },
+      context()
+    )
+
+    await expect(mutation.revokeApplianceCredential(appliance.id, context())).rejects.toThrow(/not enabled/)
+  })
+
+  it('leaves the appliance untouched when the door refuses', async () => {
+    /* A refusal that half-applied would be worse than no door at all. */
+    const appliance = await mutation.createAppliance(
+      { name: 'gate-b', serialNo: 'SN-B', brand: 'Acme', model: 'X1' },
+      context()
+    )
+    const issued = await mutation.generateApplianceSecret(appliance.id, context())
+
+    await expect(mutation.revokeApplianceCredential(issued.id, context())).rejects.toThrow()
+
+    const appuser = await shadowUserOf(issued.id)
+
+    expect(appuser!.status).toEqual(UserStatus.ACTIVATED)
+    expect(appuser!.password).toEqual(issued.accessToken)
+  })
+
+  it('still issues a working credential', async () => {
+    /*
+     * Registering and issuing are not behind either switch — they are what the product already
+     * does. Only revocation and encryption are new.
+     */
+    const appliance = await mutation.createAppliance(
+      { name: 'gate-c', serialNo: 'SN-C', brand: 'Acme', model: 'X1' },
+      context()
+    )
+    const issued = await mutation.generateApplianceSecret(appliance.id, context())
+
+    expect(issued.accessToken).toBeTruthy()
+    await expect(User.checkAuth(jwt.decode(issued.accessToken))).resolves.toBeTruthy()
+  })
+
+  it('stores the credential as it always did', async () => {
+    /*
+     * ⚠ Encryption is a write-side switch. With it off the value goes in as it always has, so a
+     * deployment that takes this release and configures nothing keeps rows in the same shape.
+     */
+    const appliance = await mutation.createAppliance(
+      { name: 'gate-d', serialNo: 'SN-D', brand: 'Acme', model: 'X1' },
+      context()
+    )
+    const issued = await mutation.generateApplianceSecret(appliance.id, context())
+
+    const appuser = await shadowUserOf(issued.id)
+
+    expect(appuser!.password).toEqual(issued.accessToken)
+    expect(appuser!.password.split('.')).toHaveLength(3)
+  })
+})
+
+describe('a token issued before this release', () => {
+  /*
+   * Such a token carries no credential serial, because the column did not exist when it was
+   * signed. Those are the tokens already in the field, and they are the ones that must not be
+   * cut off by taking this release.
+   */
+
+  it('carries no serial, and is still accepted', async () => {
+    const appliance = await mutation.createAppliance(
+      { name: 'gate-e', serialNo: 'SN-E', brand: 'Acme', model: 'X1' },
+      context()
+    )
+    const issued = await mutation.generateApplianceSecret(appliance.id, context())
+
+    /* Put the subject back the way this release found it: issued, but with no serial recorded. */
+    const appuser = await shadowUserOf(issued.id)
+    await getRepository(User).save({ ...appuser, credentialSerial: null })
+
+    const legacyToken = { ...jwt.decode(issued.accessToken) }
+    delete legacyToken.cs
+
+    await expect(User.checkAuth(legacyToken)).resolves.toBeTruthy()
+  })
+
+  it('is accepted even beside a subject that has moved on', async () => {
+    /*
+     * Two appliances in one installation, one converted and one not. The check has to be per
+     * subject — a single flag for the whole installation would cut off everything at once.
+     */
+    const a = await mutation.generateApplianceSecret(
+      (await mutation.createAppliance({ name: 'gate-f', serialNo: 'SN-F', brand: 'Acme', model: 'X1' }, context())).id,
+      context()
+    )
+    const b = await mutation.generateApplianceSecret(
+      (await mutation.createAppliance({ name: 'gate-g', serialNo: 'SN-G', brand: 'Acme', model: 'X1' }, context())).id,
+      context()
+    )
+
+    const legacy = await shadowUserOf(a.id)
+    await getRepository(User).save({ ...legacy, credentialSerial: null })
+
+    const legacyToken = { ...jwt.decode(a.accessToken) }
+    delete legacyToken.cs
+
+    await expect(User.checkAuth(legacyToken)).resolves.toBeTruthy()
+    await expect(User.checkAuth(jwt.decode(b.accessToken))).resolves.toBeTruthy()
+    expect((await shadowUserOf(b.id))!.credentialSerial).toEqual(1)
+  })
+})

package/tests/credential-serial-rule.test.ts

@@ -0,0 +1,84 @@
+import { credentialSerialMatches } from '../server/utils/credential-serial-rule'
+
+/**
+ * The one line in `checkAuth` that can refuse a token whose signature is good.
+ *
+ * Two things have to stay true at once, and they pull in opposite directions:
+ *
+ *   a token issued before this release must pass    — or taking the release cuts off the field
+ *   a token from an earlier generation must not     — or revocation does not revoke
+ *
+ * Both hang on what an absent value means on each side, which is why the cases below are mostly
+ * about absence.
+ */
+
+describe('a subject that has never been through the new path', () => {
+  it('accepts a token that carries no serial', () => {
+    /*
+     * ⚠ The tokens already in the field. They were signed before the column existed, and the
+     * subjects they name have nothing recorded. If this refused, every appliance would stop on
+     * the day the release lands.
+     */
+    expect(credentialSerialMatches({ credentialSerial: null }, {})).toBe(true)
+    expect(credentialSerialMatches({ credentialSerial: undefined }, {})).toBe(true)
+    expect(credentialSerialMatches({}, {})).toBe(true)
+  })
+
+  it('accepts a token that carries one anyway', () => {
+    /* Nothing to compare against. The subject decides whether the rule applies, not the token. */
+    expect(credentialSerialMatches({ credentialSerial: null }, { cs: 7 })).toBe(true)
+  })
+
+  it('does not fall over on a missing subject or missing claims', () => {
+    expect(credentialSerialMatches(undefined as any, {})).toBe(true)
+    expect(credentialSerialMatches({ credentialSerial: null }, undefined as any)).toBe(true)
+  })
+})
+
+describe('a subject that has moved on', () => {
+  it('accepts the generation it is on', () => {
+    expect(credentialSerialMatches({ credentialSerial: 3 }, { cs: 3 })).toBe(true)
+  })
+
+  it('refuses an earlier generation', () => {
+    /* ⚠ What revocation rests on. Without this the old token keeps working. */
+    expect(credentialSerialMatches({ credentialSerial: 3 }, { cs: 2 })).toBe(false)
+  })
+
+  it('refuses a later one too', () => {
+    /* Not a thing we issue, so it is a token from somewhere we did not sign it. */
+    expect(credentialSerialMatches({ credentialSerial: 3 }, { cs: 4 })).toBe(false)
+  })
+
+  it('refuses a token with no serial at all', () => {
+    /*
+     * ⚠ The case the whole design turns on. Once a subject has a serial, the tokens it had
+     * before that — the ones with nothing in them — are the revoked ones.
+     */
+    expect(credentialSerialMatches({ credentialSerial: 1 }, {})).toBe(false)
+    expect(credentialSerialMatches({ credentialSerial: 1 }, { cs: null })).toBe(false)
+  })
+
+  it('refuses the first generation once it has moved past it', () => {
+    expect(credentialSerialMatches({ credentialSerial: 2 }, { cs: 1 })).toBe(false)
+  })
+})
+
+describe('what it compares', () => {
+  it('does not take a string for the number', () => {
+    /*
+     * A claim arrives from a decoded token, so its type is whatever was signed. `'3'` is not the
+     * third generation — leaning the other way would let a shaped-but-wrong claim through.
+     */
+    expect(credentialSerialMatches({ credentialSerial: 3 }, { cs: '3' as any })).toBe(false)
+  })
+
+  it('treats generation zero as a generation', () => {
+    /*
+     * We start at 1, so 0 should not appear. But if it ever did, zero is a value and not an
+     * absence — reading it as absent would let everything through for that subject.
+     */
+    expect(credentialSerialMatches({ credentialSerial: 0 }, { cs: 0 })).toBe(true)
+    expect(credentialSerialMatches({ credentialSerial: 0 }, {})).toBe(false)
+  })
+})