@things-factory/auth-base 10.1.31 → 10.1.33

package/dist-server/utils/role-name-standing.js

@@ -0,0 +1,72 @@
+"use strict";
+/**
+ * Whether a role may be given a name that is already standing. (Pure rule — ADR-0062 decision 3.)
+ *
+ * ## The situation
+ *
+ * A domain sees its own roles and its parent's. Until this rule, the duplicate checks asked only
+ * about the domain itself, so a domain with a parent could be given a role whose name was already
+ * visible through inheritance. Two rows then answered to one name: every list showed both, and
+ * resolving the name picked one. An approval line could end up pointing at the one nobody looks
+ * at.
+ *
+ * ## What is refused, and what is not
+ *
+ * ```
+ * here        the domain already has this name          always refused
+ * inherited   the parent has it and this domain not     refused unless the operator says so
+ * nowhere     neither                                   stands
+ * ```
+ *
+ * ## Why the escape hatch does not ask for a different name
+ *
+ * ⚠ This is the part that is easy to get backwards. ADR-0062 decision 2 sets out the only path
+ * for moving a domain off an inherited structure: **stand the role up here → move the people to
+ * the role of the same name → cut the parent last.** The name being the same is the point of it
+ * — the domain's own role is standing up to *replace* what it inherits, and once the parent is
+ * cut there is one name again.
+ *
+ * So requiring a different name would close the one route decision 2 defines. The escape is the
+ * operator saying, in as many words, that this domain stands its own — and the name stays.
+ * Asking for a different name remains available on top of that, for when somebody genuinely
+ * wants a second seat with the same privileges; it is a choice, never a requirement.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nameStands = nameStands;
+exports.refusesName = refusesName;
+/**
+ * Where the name stands.
+ *
+ * A role found in neither this domain nor its parent is `nowhere` — the caller is expected to
+ * have looked in those two places, and a row from somewhere else is not this domain's business.
+ */
+function nameStands(found, domain) {
+    const where = found?.domainId;
+    if (!where) {
+        return 'nowhere';
+    }
+    if (where === domain?.id) {
+        return 'here';
+    }
+    if (domain?.parentId && where === domain.parentId) {
+        return 'inherited';
+    }
+    return 'nowhere';
+}
+/**
+ * Does the name refuse?
+ *
+ * `separately` is the operator saying this domain stands its own of that name. It reaches only
+ * the inherited case — a name already taken **in this domain** is not a thing anybody can opt
+ * into, because the two rows would be indistinguishable in every respect.
+ */
+function refusesName(standing, separately) {
+    if (standing === 'here') {
+        return true;
+    }
+    if (standing === 'inherited') {
+        return !separately;
+    }
+    return false;
+}
+//# sourceMappingURL=role-name-standing.js.map

package/dist-server/utils/role-name-standing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"role-name-standing.js","sourceRoot":"","sources":["../../server/utils/role-name-standing.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;;AAsBH,gCAgBC;AASD,kCAUC;AAzCD;;;;;GAKG;AACH,SAAgB,UAAU,CAAC,KAAmB,EAAE,MAAoB;IAClE,MAAM,KAAK,GAAG,KAAK,EAAE,QAAQ,CAAA;IAE7B,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,SAAS,CAAA;IAClB,CAAC;IAED,IAAI,KAAK,KAAK,MAAM,EAAE,EAAE,EAAE,CAAC;QACzB,OAAO,MAAM,CAAA;IACf,CAAC;IAED,IAAI,MAAM,EAAE,QAAQ,IAAI,KAAK,KAAK,MAAM,CAAC,QAAQ,EAAE,CAAC;QAClD,OAAO,WAAW,CAAA;IACpB,CAAC;IAED,OAAO,SAAS,CAAA;AAClB,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,WAAW,CAAC,QAAsB,EAAE,UAAoB;IACtE,IAAI,QAAQ,KAAK,MAAM,EAAE,CAAC;QACxB,OAAO,IAAI,CAAA;IACb,CAAC;IAED,IAAI,QAAQ,KAAK,WAAW,EAAE,CAAC;QAC7B,OAAO,CAAC,UAAU,CAAA;IACpB,CAAC;IAED,OAAO,KAAK,CAAA;AACd,CAAC","sourcesContent":["/**\n * Whether a role may be given a name that is already standing. (Pure rule — ADR-0062 decision 3.)\n *\n * ## The situation\n *\n * A domain sees its own roles and its parent's. Until this rule, the duplicate checks asked only\n * about the domain itself, so a domain with a parent could be given a role whose name was already\n * visible through inheritance. Two rows then answered to one name: every list showed both, and\n * resolving the name picked one. An approval line could end up pointing at the one nobody looks\n * at.\n *\n * ## What is refused, and what is not\n *\n * ```\n * here        the domain already has this name          always refused\n * inherited   the parent has it and this domain not     refused unless the operator says so\n * nowhere     neither                                   stands\n * ```\n *\n * ## Why the escape hatch does not ask for a different name\n *\n * ⚠ This is the part that is easy to get backwards. ADR-0062 decision 2 sets out the only path\n * for moving a domain off an inherited structure: **stand the role up here → move the people to\n * the role of the same name → cut the parent last.** The name being the same is the point of it\n * — the domain's own role is standing up to *replace* what it inherits, and once the parent is\n * cut there is one name again.\n *\n * So requiring a different name would close the one route decision 2 defines. The escape is the\n * operator saying, in as many words, that this domain stands its own — and the name stays.\n * Asking for a different name remains available on top of that, for when somebody genuinely\n * wants a second seat with the same privileges; it is a choice, never a requirement.\n */\n\n/** Where a role of this name already stands, seen from the domain that is asking. */\nexport type NameStanding = 'nowhere' | 'here' | 'inherited'\n\n/** The domain asking. `parentId` absent means it inherits from nobody. */\nexport type AskingDomain = {\n  id: string\n  parentId?: string | null\n}\n\n/** A role that was found carrying the name, or nothing. */\nexport type StandingRole = {\n  domainId?: string | null\n} | null | undefined\n\n/**\n * Where the name stands.\n *\n * A role found in neither this domain nor its parent is `nowhere` — the caller is expected to\n * have looked in those two places, and a row from somewhere else is not this domain's business.\n */\nexport function nameStands(found: StandingRole, domain: AskingDomain): NameStanding {\n  const where = found?.domainId\n\n  if (!where) {\n    return 'nowhere'\n  }\n\n  if (where === domain?.id) {\n    return 'here'\n  }\n\n  if (domain?.parentId && where === domain.parentId) {\n    return 'inherited'\n  }\n\n  return 'nowhere'\n}\n\n/**\n * Does the name refuse?\n *\n * `separately` is the operator saying this domain stands its own of that name. It reaches only\n * the inherited case — a name already taken **in this domain** is not a thing anybody can opt\n * into, because the two rows would be indistinguishable in every respect.\n */\nexport function refusesName(standing: NameStanding, separately?: boolean): boolean {\n  if (standing === 'here') {\n    return true\n  }\n\n  if (standing === 'inherited') {\n    return !separately\n  }\n\n  return false\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/auth-base",
-  "version": "10.1.31",
+  "version": "10.1.33",
   "main": "dist-server/index.js",
   "browser": "dist-client/index.js",
   "things-factory": true,
@@ -34,9 +34,9 @@
     "@reduxjs/toolkit": "^2.2.5",
     "@simplewebauthn/browser": "^13.0.0",
     "@simplewebauthn/server": "^13.0.0",
-    "@things-factory/email-base": "^10.1.31",
+    "@things-factory/email-base": "^10.1.33",
     "@things-factory/env": "^10.1.20",
-    "@things-factory/shell": "^10.1.31",
+    "@things-factory/shell": "^10.1.33",
     "@things-factory/utils": "^10.1.20",
     "@types/webappsec-credential-management": "^0.6.9",
     "jsonwebtoken": "^9.0.0",
@@ -48,5 +48,5 @@
     "passport-jwt": "^4.0.0",
     "passport-local": "^1.0.0"
   },
-  "gitHead": "5213e6f9913b40ea2618a2111d9884b792dbaa01"
+  "gitHead": "7fb7b6587846b5ff6ee7a4983652d9561b4d6b2c"
 }

package/tests/app-binding-delete-db.test.ts

@@ -0,0 +1,188 @@
+/**
+ * `deleteAppBinding` — cutting one client off without touching the application.
+ *
+ * ── What the door was ───────────────────────────────────────────────────────
+ * It read the domain out of the context, used it for nothing, and ran
+ *
+ *     getRepository(User).delete({ id })
+ *
+ * That criteria names neither the kind of row nor the tenant. `AppBinding` is a `User` wearing
+ * a type, so every account in the installation is the same kind of row as the one this was for:
+ * a person, a domain owner, an appliance's shadow user, another tenant's binding. Any id at all
+ * deleted that row and answered true.
+ *
+ * It carried no `@privilege` either, so the schema recorded it as open and anyone holding a
+ * valid token could reach it.
+ *
+ * ── Why revocation is a delete here ─────────────────────────────────────────
+ * An appliance keeps its identity when its credential is taken away, because past rows point at
+ * it as creator and updater and a new secret should land on the same subject. A binding is not
+ * like that: it is created by the OAuth2 exchange whenever a client is granted access, and the
+ * grant is the only thing it records. Deleting it is the revocation — there is no second state
+ * for it to be in (ADR-0055).
+ *
+ * ⚠ sqlite (`tests/db.ts`).
+ */
+
+import { closeAuthDatabase, Domain, getRepository, openAuthDatabase, resetAuthDatabase } from './db'
+import { loadCompiled } from './compiled'
+
+const { Application } = loadCompiled('service/application/application')
+const { User, UserStatus } = loadCompiled('service/user/user')
+const { AppBindingMutation } = loadCompiled('service/app-binding/app-binding-mutation')
+const { ApplicationMutation } = loadCompiled('service/application/application-mutation')
+
+const mutation = new AppBindingMutation()
+const applications = new ApplicationMutation()
+
+let ours: any
+let theirs: any
+let actor: any
+
+function context(d: any) {
+  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 makeApplication(name: string, d: any) {
+  return await applications.createApplication(
+    {
+      name,
+      email: `${name}@acme.z`,
+      url: `https://${name}.example.com`,
+      redirectUrl: `https://${name}.example.com/callback`,
+      type: 'OTHERS'
+    },
+    context(d)
+  )
+}
+
+async function bind(application: any, label: string, d: any) {
+  return await getRepository(User).save({
+    username: `${label}@acme`,
+    email: `${label}@acme`,
+    name: label,
+    userType: 'application',
+    reference: application.id,
+    status: UserStatus.ACTIVATED,
+    domains: [d]
+  })
+}
+
+async function stillThere(id: string) {
+  return !!(await getRepository(User).findOneBy({ id }))
+}
+
+beforeAll(async () => {
+  await openAuthDatabase()
+})
+
+afterAll(async () => {
+  await closeAuthDatabase()
+})
+
+beforeEach(async () => {
+  await resetAuthDatabase()
+
+  ours = await getRepository(Domain).save({ name: 'acme', subdomain: 'acme' })
+  theirs = await getRepository(Domain).save({ name: 'beta', subdomain: 'beta' })
+  actor = await getRepository(User).save({
+    username: 'operator@acme.z',
+    email: 'operator@acme.z',
+    name: 'operator',
+    status: UserStatus.ACTIVATED,
+    domains: [ours]
+  })
+})
+
+describe('cutting off a binding of ours', () => {
+  it('deletes it', async () => {
+    const application = await makeApplication('billing', ours)
+    const binding = await bind(application, 'binding-a', ours)
+
+    await mutation.deleteAppBinding(binding.id, context(ours))
+
+    expect(await stillThere(binding.id)).toBe(false)
+  })
+
+  it('leaves the application and its other bindings alone', async () => {
+    /* Revoking one client is not deleting the application. */
+    const application = await makeApplication('billing', ours)
+    const going = await bind(application, 'binding-a', ours)
+    const staying = await bind(application, 'binding-b', ours)
+
+    await mutation.deleteAppBinding(going.id, context(ours))
+
+    expect(await stillThere(staying.id)).toBe(true)
+    expect(await getRepository(Application).findOneBy({ id: application.id })).not.toBeNull()
+  })
+})
+
+describe('an id that is not a binding of ours', () => {
+  it('does not delete a person', async () => {
+    /*
+     * ⚠ The worst of these. A person's account is the same kind of row as a binding, so
+     * `delete({ id })` took it with the same answer — and the caller did not have to be anyone
+     * in particular, because the mutation carried no privilege at all.
+     */
+    const person = await getRepository(User).save({
+      username: 'kim@acme.z',
+      email: 'kim@acme.z',
+      name: 'kim',
+      status: UserStatus.ACTIVATED,
+      domains: [ours]
+    })
+
+    await mutation.deleteAppBinding(person.id, context(ours))
+
+    expect(await stillThere(person.id)).toBe(true)
+  })
+
+  it('does not delete an appliance shadow user', async () => {
+    /*
+     * ⚠ Deleting one stops the device at its next request and leaves the appliance on screen
+     * looking registered — the same end state as the appliance delete leak, reached from here.
+     */
+    const applianceUser = await getRepository(User).save({
+      username: 'device@acme',
+      email: 'device@acme',
+      name: 'device',
+      userType: 'appliance',
+      reference: 'some-appliance-id',
+      status: UserStatus.ACTIVATED,
+      domains: [ours]
+    })
+
+    await mutation.deleteAppBinding(applianceUser.id, context(ours))
+
+    expect(await stillThere(applianceUser.id)).toBe(true)
+  })
+
+  it('does not delete another tenant s binding', async () => {
+    /* ⚠ The tenant boundary. `appBinding` already refuses to read one; this deleted it. */
+    const application = await makeApplication('billing', theirs)
+    const foreign = await bind(application, 'binding-theirs', theirs)
+
+    await mutation.deleteAppBinding(foreign.id, context(ours))
+
+    expect(await stillThere(foreign.id)).toBe(true)
+  })
+
+  it('answers the same whether the id was ours, theirs, or nothing', async () => {
+    /*
+     * Telling them apart would confirm that some id is real somewhere else — the reason
+     * `appBinding` answers nothing for both cases.
+     */
+    const application = await makeApplication('billing', theirs)
+    const foreign = await bind(application, 'binding-theirs', theirs)
+
+    await expect(mutation.deleteAppBinding(foreign.id, context(ours))).resolves.toBe(true)
+    await expect(mutation.deleteAppBinding('no-such-id', context(ours))).resolves.toBe(true)
+  })
+})

package/tests/appliance-credential-state-db.test.ts

@@ -0,0 +1,207 @@
+/**
+ * What the screen is allowed to ask about a credential (ADR-0085, the revocation screen).
+ *
+ * Two questions, and they are not the same one:
+ *
+ *   applianceCredentialRevocable   does revoking work here at all?
+ *   Appliance.credentialRevoked    has this one been revoked?
+ *
+ * ── Why the first exists ────────────────────────────────────────────────────
+ * Revocation is behind `credential/revocable`, and the client cannot read configuration. Without
+ * an answer the screen either hides a feature the installation asked for or shows a button that
+ * always refuses — and a button that always refuses reads as a broken product rather than as
+ * something nobody turned on.
+ *
+ * ── Why the second exists ───────────────────────────────────────────────────
+ * Revoking clears `accessToken`, so a revoked appliance and one that was never issued a
+ * credential look identical on screen: an empty box. They are opposite situations. The state
+ * that tells them apart is on the shadow user, not on the appliance row, so the field has to be
+ * resolved rather than read.
+ *
+ * ⚠ sqlite (`tests/db.ts`).
+ */
+
+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 { User, UserStatus } = loadCompiled('service/user/user')
+const { ApplianceMutation } = loadCompiled('service/appliance/appliance-mutation')
+const { ApplianceQuery } = loadCompiled('service/appliance/appliance-query')
+
+const mutation = new ApplianceMutation()
+const query = new ApplianceQuery()
+
+const configGet = config.get
+
+function revocationOff() {
+  config.get = configGet
+}
+
+function revocationOn() {
+  config.get = ((key: string, fallback?: any) =>
+    key === 'credential/revocable' ? true : configGet(key, fallback)) as typeof config.get
+}
+
+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 register(name: string) {
+  return await mutation.createAppliance({ name, serialNo: `${name}-SN`, brand: 'Acme', model: 'X1' }, context())
+}
+
+beforeAll(async () => {
+  await openAuthDatabase()
+})
+
+afterAll(async () => {
+  revocationOff()
+  await closeAuthDatabase()
+})
+
+beforeEach(async () => {
+  revocationOff()
+  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('does revoking work here', () => {
+  it('says no where the installation configured nothing', async () => {
+    /*
+     * ⚠ The default. An installation that takes this release and changes no configuration must
+     * not grow a button, because the mutation behind it answers 404.
+     */
+    expect(await query.applianceCredentialRevocable()).toBe(false)
+  })
+
+  it('says yes once the installation turns it on', async () => {
+    revocationOn()
+
+    expect(await query.applianceCredentialRevocable()).toBe(true)
+  })
+
+  it('answers the same thing the door does', async () => {
+    /*
+     * ⚠ The two have to move together. If the answer said yes while the mutation refused, the
+     * screen would offer an action that cannot be completed — which is the exact thing this
+     * query exists to prevent.
+     */
+    const appliance = await register('gate-a')
+
+    expect(await query.applianceCredentialRevocable()).toBe(false)
+    await expect(mutation.revokeApplianceCredential(appliance.id, context())).rejects.toThrow(/not enabled/)
+
+    revocationOn()
+
+    expect(await query.applianceCredentialRevocable()).toBe(true)
+    await expect(mutation.revokeApplianceCredential(appliance.id, context())).resolves.toBeTruthy()
+  })
+})
+
+describe('has this one been revoked', () => {
+  it('says no for an appliance nobody has issued a credential for', async () => {
+    /*
+     * ⚠ The case the whole field is for. This appliance and a revoked one both show an empty
+     * access token; only this answer separates "waiting to be set up" from "deliberately shut
+     * off".
+     */
+    const appliance = await register('gate-b')
+
+    expect(await query.credentialRevoked(appliance)).toBe(false)
+  })
+
+  it('says no for one holding a working credential', async () => {
+    const issued = await mutation.generateApplianceSecret((await register('gate-c')).id, context())
+
+    expect(await query.credentialRevoked(issued)).toBe(false)
+  })
+
+  it('says yes once it has been revoked', async () => {
+    revocationOn()
+
+    const issued = await mutation.generateApplianceSecret((await register('gate-d')).id, context())
+    const revoked = await mutation.revokeApplianceCredential(issued.id, context())
+
+    expect(await query.credentialRevoked(revoked)).toBe(true)
+  })
+
+  it('says no again after a new credential is issued', async () => {
+    /*
+     * Re-issuing puts the shadow user back to ACTIVATED, which is what makes the new token
+     * usable. The screen has to follow, or a working appliance keeps saying it was revoked.
+     */
+    revocationOn()
+
+    const issued = await mutation.generateApplianceSecret((await register('gate-e')).id, context())
+    await mutation.revokeApplianceCredential(issued.id, context())
+    const reissued = await mutation.generateApplianceSecret(issued.id, context())
+
+    expect(await query.credentialRevoked(reissued)).toBe(false)
+  })
+
+  it('does not read one appliance state onto another', async () => {
+    revocationOn()
+
+    const a = await mutation.generateApplianceSecret((await register('gate-f')).id, context())
+    const b = await mutation.generateApplianceSecret((await register('gate-g')).id, context())
+
+    await mutation.revokeApplianceCredential(a.id, context())
+
+    expect(await query.credentialRevoked(await getRepository(Appliance).findOneBy({ id: a.id }))).toBe(true)
+    expect(await query.credentialRevoked(await getRepository(Appliance).findOneBy({ id: b.id }))).toBe(false)
+  })
+
+  it('reads the shadow user rather than the cleared column', async () => {
+    /*
+     * ⚠ The tempting shortcut is "no access token means revoked". It is wrong in both
+     * directions: a registered appliance has no token and is not revoked, and clearing the
+     * column by hand does not stop anything — the JWT verifies on its signature.
+     *
+     * So an appliance whose token is emptied without going through revocation is not revoked,
+     * and one whose status is INACTIVE is, whatever the column holds.
+     */
+    const issued = await mutation.generateApplianceSecret((await register('gate-h')).id, context())
+
+    await getRepository(Appliance).save({ ...issued, accessToken: null })
+    expect(await query.credentialRevoked(await getRepository(Appliance).findOneBy({ id: issued.id }))).toBe(false)
+
+    const appuser = await getRepository(User).findOneBy({ reference: issued.id, userType: 'appliance' })
+    await getRepository(User).save({ ...appuser, status: UserStatus.INACTIVE })
+
+    expect(await query.credentialRevoked(await getRepository(Appliance).findOneBy({ id: issued.id }))).toBe(true)
+  })
+
+  it('does not call a locked appliance revoked', async () => {
+    /*
+     * LOCKED is the failed-sign-in lockout and it ages out by itself, which is why revocation
+     * does not use it. Reporting it as revoked would tell the reader a lock is permanent.
+     */
+    const issued = await mutation.generateApplianceSecret((await register('gate-i')).id, context())
+
+    const appuser = await getRepository(User).findOneBy({ reference: issued.id, userType: 'appliance' })
+    await getRepository(User).save({ ...appuser, status: UserStatus.LOCKED })
+
+    expect(await query.credentialRevoked(await getRepository(Appliance).findOneBy({ id: issued.id }))).toBe(false)
+  })
+})

package/tests/appliance-delete-db.test.ts

@@ -0,0 +1,119 @@
+/**
+ * Deleting an appliance stays inside the tenant that asked.
+ *
+ * ── The order the deletes happen in ─────────────────────────────────────────
+ * An appliance is two rows: the appliance itself, which carries a domain, and a shadow `User`
+ * standing in for the device, which is found by `reference` and carries no tenant of its own.
+ *
+ * `deleteAppliance` deleted the shadow user first and scoped only the appliance row afterwards.
+ * So an id belonging to somebody else deleted their device's identity and then failed to delete
+ * their appliance — the row stayed on their screen looking registered, and the device behind it
+ * stopped at the next request, because `checkAuth` looks the subject up by the id in the token
+ * and there was no longer a subject. Nothing in the answer said so: the mutation returns true.
+ *
+ * ⚠ sqlite (`tests/db.ts`).
+ */
+
+import { closeAuthDatabase, Domain, getRepository, openAuthDatabase, resetAuthDatabase } from './db'
+import { loadCompiled } from './compiled'
+
+const { Appliance } = loadCompiled('service/appliance/appliance')
+const { User, UserStatus } = loadCompiled('service/user/user')
+const { ApplianceMutation } = loadCompiled('service/appliance/appliance-mutation')
+
+const mutation = new ApplianceMutation()
+
+let ours: any
+let theirs: any
+let actor: any
+
+function context(d: any) {
+  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 register(name: string, d: any) {
+  return await mutation.createAppliance({ name, serialNo: `${name}-SN`, brand: 'Acme', model: 'X1' }, context(d))
+}
+
+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()
+
+  ours = await getRepository(Domain).save({ name: 'acme', subdomain: 'acme' })
+  theirs = await getRepository(Domain).save({ name: 'beta', subdomain: 'beta' })
+  actor = await getRepository(User).save({
+    username: 'operator@acme.z',
+    email: 'operator@acme.z',
+    name: 'operator',
+    status: UserStatus.ACTIVATED,
+    domains: [ours]
+  })
+})
+
+describe('deleting our own appliance', () => {
+  it('takes the appliance and its shadow user', async () => {
+    const appliance = await register('gate-a', ours)
+    await mutation.generateApplianceSecret(appliance.id, context(ours))
+
+    await mutation.deleteAppliance(appliance.id, context(ours))
+
+    expect(await getRepository(Appliance).findOneBy({ id: appliance.id })).toBeNull()
+    expect(await shadowUserOf(appliance.id)).toBeNull()
+  })
+})
+
+describe('an id that belongs to another tenant', () => {
+  it('leaves their appliance where it is', async () => {
+    const foreign = await register('their-gate', theirs)
+
+    await mutation.deleteAppliance(foreign.id, context(ours))
+
+    expect(await getRepository(Appliance).findOneBy({ id: foreign.id })).not.toBeNull()
+  })
+
+  it('leaves their device able to authenticate', async () => {
+    /*
+     * ⚠ The case. Deleting the shadow user before checking the tenant stopped somebody else's
+     * device while leaving their appliance row on screen looking registered — no screen would
+     * show what happened, and the fix from their side is to issue a new secret for a device
+     * that had a working one.
+     */
+    const foreign = await register('their-gate', theirs)
+    const issued = await mutation.generateApplianceSecret(foreign.id, context(theirs))
+
+    await mutation.deleteAppliance(foreign.id, context(ours))
+
+    expect(await shadowUserOf(foreign.id)).not.toBeNull()
+
+    const jwt = require('jsonwebtoken')
+    await expect(User.checkAuth(jwt.decode(issued.accessToken))).resolves.toBeTruthy()
+  })
+
+  it('does not take ours down with it either way', async () => {
+    const mine = await register('gate-a', ours)
+    const foreign = await register('their-gate', theirs)
+
+    await mutation.deleteAppliance(foreign.id, context(ours))
+
+    expect(await getRepository(Appliance).findOneBy({ id: mine.id })).not.toBeNull()
+    expect(await shadowUserOf(mine.id)).not.toBeNull()
+  })
+})