@things-factory/shell 10.1.29 → 10.1.33

package/dist-server/typeorm/encrypt-transform.d.ts

@@ -1,7 +1,26 @@
 import { ValueTransformer } from 'typeorm';
 /**
- * ValueTransformer object for encrypting and decrypting database entity field values.
- * Used in TypeORM entities to encrypt field values before storing them in the database
- * and decrypt values when retrieving them from the database.
+ * Encrypting a database column, and reading one that may not be encrypted yet.
+ *
+ * ── Reading tells two failures apart ────────────────────────────────────────
+ * This used to answer `null` whenever decryption threw, which folded two very different
+ * things into one:
+ *
+ *     the value was written before this column was encrypted   →  it is plaintext
+ *     the value is ciphertext and the key cannot open it       →  something is wrong
+ *
+ * Both came back as "there is no value". A deployment with the wrong `dataEncryptionKey`
+ * therefore looked like a system holding no credentials at all — the rows were intact, one
+ * line went to the console, and nothing said which row or how many. Devices kept
+ * authenticating, because a signed token never consults these columns, so only the screens
+ * lost the values.
+ *
+ * So: a value that is not ciphertext-shaped is returned as it is, which is what lets a column
+ * be encrypted without a flag day. A value that IS ciphertext-shaped and will not open throws,
+ * because that is a broken key and not an absent value.
  */
 export declare const encryptTransformer: ValueTransformer;
+/** Raised when a value is ciphertext and the configured key does not open it. */
+export declare class DecryptionFailed extends Error {
+    constructor(cause: unknown);
+}

package/dist-server/typeorm/encrypt-transform.js

@@ -1,36 +1,52 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.encryptTransformer = void 0;
+exports.DecryptionFailed = exports.encryptTransformer = void 0;
 const crypto_1 = require("crypto");
 const get_data_encryption_key_js_1 = require("./get-data-encryption-key.js");
 const ALGORITHM = 'aes-256-cbc';
-const KEY_LENGTH = 32;
-const SALT_LENGTH = 16;
 const IV_LENGTH = 16;
 /**
- * ValueTransformer object for encrypting and decrypting database entity field values.
- * Used in TypeORM entities to encrypt field values before storing them in the database
- * and decrypt values when retrieving them from the database.
+ * What this writes: `<iv as hex>:<ciphertext as hex>`. The IV is 16 bytes, so the prefix is
+ * exactly 32 hex characters, and the body is hex of even length.
+ *
+ * Reading matches on that shape rather than trying and seeing what happens, because the two
+ * failures below have to stay apart.
  */
-exports.encryptTransformer = {
-    /**
-     * Encrypts the entity field value before storing it in the database.
-     * @param {string} entityValue - Unencrypted entity field value
-     * @returns {string} - Encrypted string
-     */
-    to: (entityValue) => encrypt(entityValue), // DB에 저장하기 전에 암호화
-    /**
-     * Decrypts the encrypted database value when retrieving it from the database.
-     * @param {string} databaseValue - Encrypted database field value
-     * @returns {string} - Decrypted string
-     */
-    from: (databaseValue) => decrypt(databaseValue) // DB에서 값을 가져올 때 복호화
-};
+const CIPHERTEXT = /^[0-9a-f]{32}:(?:[0-9a-f]{2})+$/;
 /**
- * Encrypts the given text using the AES-256-CBC algorithm.
- * @param {string} text - Text to encrypt
- * @returns {string} - Encrypted string
+ * Encrypting a database column, and reading one that may not be encrypted yet.
+ *
+ * ── Reading tells two failures apart ────────────────────────────────────────
+ * This used to answer `null` whenever decryption threw, which folded two very different
+ * things into one:
+ *
+ *     the value was written before this column was encrypted   →  it is plaintext
+ *     the value is ciphertext and the key cannot open it       →  something is wrong
+ *
+ * Both came back as "there is no value". A deployment with the wrong `dataEncryptionKey`
+ * therefore looked like a system holding no credentials at all — the rows were intact, one
+ * line went to the console, and nothing said which row or how many. Devices kept
+ * authenticating, because a signed token never consults these columns, so only the screens
+ * lost the values.
+ *
+ * So: a value that is not ciphertext-shaped is returned as it is, which is what lets a column
+ * be encrypted without a flag day. A value that IS ciphertext-shaped and will not open throws,
+ * because that is a broken key and not an absent value.
  */
+exports.encryptTransformer = {
+    to: (entityValue) => encrypt(entityValue),
+    from: (databaseValue) => decrypt(databaseValue)
+};
+/** Raised when a value is ciphertext and the configured key does not open it. */
+class DecryptionFailed extends Error {
+    constructor(cause) {
+        super('an encrypted column could not be decrypted with the configured dataEncryptionKey. ' +
+            'The value is still in the database — this is a key problem, not a missing value.');
+        this.name = 'DecryptionFailed';
+        this.cause = cause;
+    }
+}
+exports.DecryptionFailed = DecryptionFailed;
 function encrypt(text) {
     if (!text) {
         return null;
@@ -40,25 +56,25 @@ function encrypt(text) {
     const encrypted = Buffer.concat([cipher.update(text, 'utf8'), cipher.final()]);
     return `${iv.toString('hex')}:${encrypted.toString('hex')}`;
 }
-/**
- * Decrypts the given encrypted text.
- * @param {string} text - Encrypted text to decrypt
- * @returns {string} - Decrypted string
- */
 function decrypt(text) {
     if (!text) {
         return null;
     }
+    /*
+     * Written before this column was encrypted. Handing it back unchanged is the whole of the
+     * backward compatibility: a column can start encrypting while the rows already in it stay
+     * readable, and each row converts the next time something writes it.
+     */
+    if (!CIPHERTEXT.test(text)) {
+        return text;
+    }
     try {
-        const parts = text.split(':');
-        const iv = Buffer.from(parts.shift(), 'hex');
-        const encryptedText = Buffer.from(parts.join(':'), 'hex');
-        const decipher = (0, crypto_1.createDecipheriv)(ALGORITHM, get_data_encryption_key_js_1.dataEncryptionKey, iv);
-        return Buffer.concat([decipher.update(encryptedText), decipher.final()]).toString('utf8');
+        const [ivHex, bodyHex] = text.split(':');
+        const decipher = (0, crypto_1.createDecipheriv)(ALGORITHM, get_data_encryption_key_js_1.dataEncryptionKey, Buffer.from(ivHex, 'hex'));
+        return Buffer.concat([decipher.update(Buffer.from(bodyHex, 'hex')), decipher.final()]).toString('utf8');
     }
     catch (err) {
-        console.error(`decryption for encrypted field failed in encryptTransformer`);
-        return null;
+        throw new DecryptionFailed(err);
     }
 }
 //# sourceMappingURL=encrypt-transform.js.map

package/dist-server/typeorm/encrypt-transform.js.map

@@ -1 +1 @@
-{"version":3,"file":"encrypt-transform.js","sourceRoot":"","sources":["../../server/typeorm/encrypt-transform.ts"],"names":[],"mappings":";;;AACA,mCAAkF;AAElF,6EAAgE;AAEhE,MAAM,SAAS,GAAG,aAAa,CAAA;AAC/B,MAAM,UAAU,GAAG,EAAE,CAAA;AACrB,MAAM,WAAW,GAAG,EAAE,CAAA;AACtB,MAAM,SAAS,GAAG,EAAE,CAAA;AAEpB;;;;GAIG;AACU,QAAA,kBAAkB,GAAqB;IAClD;;;;OAIG;IACH,EAAE,EAAE,CAAC,WAAmB,EAAE,EAAE,CAAC,OAAO,CAAC,WAAW,CAAC,EAAE,kBAAkB;IAErE;;;;OAIG;IACH,IAAI,EAAE,CAAC,aAAqB,EAAE,EAAE,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC,oBAAoB;CAC7E,CAAA;AAED;;;;GAIG;AACH,SAAS,OAAO,CAAC,IAAY;IAC3B,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,OAAO,IAAI,CAAA;IACb,CAAC;IAED,MAAM,EAAE,GAAG,IAAA,oBAAW,EAAC,SAAS,CAAC,CAAA;IACjC,MAAM,MAAM,GAAG,IAAA,uBAAc,EAAC,SAAS,EAAE,8CAAiB,EAAE,EAAE,CAAC,CAAA;IAC/D,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAA;IAE9E,OAAO,GAAG,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,SAAS,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAA;AAC7D,CAAC;AAED;;;;GAIG;AACH,SAAS,OAAO,CAAC,IAAY;IAC3B,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,OAAO,IAAI,CAAA;IACb,CAAC;IAED,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;QAC7B,MAAM,EAAE,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,EAAE,KAAK,CAAC,CAAA;QAC5C,MAAM,aAAa,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,KAAK,CAAC,CAAA;QACzD,MAAM,QAAQ,GAAG,IAAA,yBAAgB,EAAC,SAAS,EAAE,8CAAiB,EAAE,EAAE,CAAC,CAAA;QAEnE,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,aAAa,CAAC,EAAE,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAA;IAC3F,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,CAAC,KAAK,CAAC,6DAA6D,CAAC,CAAA;QAC5E,OAAO,IAAI,CAAA;IACb,CAAC;AACH,CAAC","sourcesContent":["import { ValueTransformer } from 'typeorm'\nimport { createCipheriv, createDecipheriv, randomBytes, scryptSync } from 'crypto'\n\nimport { dataEncryptionKey } from './get-data-encryption-key.js'\n\nconst ALGORITHM = 'aes-256-cbc'\nconst KEY_LENGTH = 32\nconst SALT_LENGTH = 16\nconst IV_LENGTH = 16\n\n/**\n * ValueTransformer object for encrypting and decrypting database entity field values.\n * Used in TypeORM entities to encrypt field values before storing them in the database\n * and decrypt values when retrieving them from the database.\n */\nexport const encryptTransformer: ValueTransformer = {\n  /**\n   * Encrypts the entity field value before storing it in the database.\n   * @param {string} entityValue - Unencrypted entity field value\n   * @returns {string} - Encrypted string\n   */\n  to: (entityValue: string) => encrypt(entityValue), // DB에 저장하기 전에 암호화\n\n  /**\n   * Decrypts the encrypted database value when retrieving it from the database.\n   * @param {string} databaseValue - Encrypted database field value\n   * @returns {string} - Decrypted string\n   */\n  from: (databaseValue: string) => decrypt(databaseValue) // DB에서 값을 가져올 때 복호화\n}\n\n/**\n * Encrypts the given text using the AES-256-CBC algorithm.\n * @param {string} text - Text to encrypt\n * @returns {string} - Encrypted string\n */\nfunction encrypt(text: string): string {\n  if (!text) {\n    return null\n  }\n\n  const iv = randomBytes(IV_LENGTH)\n  const cipher = createCipheriv(ALGORITHM, dataEncryptionKey, iv)\n  const encrypted = Buffer.concat([cipher.update(text, 'utf8'), cipher.final()])\n\n  return `${iv.toString('hex')}:${encrypted.toString('hex')}`\n}\n\n/**\n * Decrypts the given encrypted text.\n * @param {string} text - Encrypted text to decrypt\n * @returns {string} - Decrypted string\n */\nfunction decrypt(text: string): string {\n  if (!text) {\n    return null\n  }\n\n  try {\n    const parts = text.split(':')\n    const iv = Buffer.from(parts.shift(), 'hex')\n    const encryptedText = Buffer.from(parts.join(':'), 'hex')\n    const decipher = createDecipheriv(ALGORITHM, dataEncryptionKey, iv)\n\n    return Buffer.concat([decipher.update(encryptedText), decipher.final()]).toString('utf8')\n  } catch (err) {\n    console.error(`decryption for encrypted field failed in encryptTransformer`)\n    return null\n  }\n}\n"]}
+{"version":3,"file":"encrypt-transform.js","sourceRoot":"","sources":["../../server/typeorm/encrypt-transform.ts"],"names":[],"mappings":";;;AACA,mCAAsE;AAEtE,6EAAgE;AAEhE,MAAM,SAAS,GAAG,aAAa,CAAA;AAC/B,MAAM,SAAS,GAAG,EAAE,CAAA;AAEpB;;;;;;GAMG;AACH,MAAM,UAAU,GAAG,iCAAiC,CAAA;AAEpD;;;;;;;;;;;;;;;;;;;GAmBG;AACU,QAAA,kBAAkB,GAAqB;IAClD,EAAE,EAAE,CAAC,WAAmB,EAAE,EAAE,CAAC,OAAO,CAAC,WAAW,CAAC;IACjD,IAAI,EAAE,CAAC,aAAqB,EAAE,EAAE,CAAC,OAAO,CAAC,aAAa,CAAC;CACxD,CAAA;AAED,iFAAiF;AACjF,MAAa,gBAAiB,SAAQ,KAAK;IACzC,YAAY,KAAc;QACxB,KAAK,CACH,oFAAoF;YAClF,kFAAkF,CACrF,CAAA;QAED,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAC7B;QAAC,IAAY,CAAC,KAAK,GAAG,KAAK,CAAA;IAC9B,CAAC;CACF;AAVD,4CAUC;AAED,SAAS,OAAO,CAAC,IAAY;IAC3B,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,OAAO,IAAI,CAAA;IACb,CAAC;IAED,MAAM,EAAE,GAAG,IAAA,oBAAW,EAAC,SAAS,CAAC,CAAA;IACjC,MAAM,MAAM,GAAG,IAAA,uBAAc,EAAC,SAAS,EAAE,8CAAiB,EAAE,EAAE,CAAC,CAAA;IAC/D,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAA;IAE9E,OAAO,GAAG,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,SAAS,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAA;AAC7D,CAAC;AAED,SAAS,OAAO,CAAC,IAAY;IAC3B,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,OAAO,IAAI,CAAA;IACb,CAAC;IAED;;;;OAIG;IACH,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAC3B,OAAO,IAAI,CAAA;IACb,CAAC;IAED,IAAI,CAAC;QACH,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;QACxC,MAAM,QAAQ,GAAG,IAAA,yBAAgB,EAAC,SAAS,EAAE,8CAAiB,EAAE,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAA;QAE1F,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAA;IACzG,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,gBAAgB,CAAC,GAAG,CAAC,CAAA;IACjC,CAAC;AACH,CAAC","sourcesContent":["import { ValueTransformer } from 'typeorm'\nimport { createCipheriv, createDecipheriv, randomBytes } from 'crypto'\n\nimport { dataEncryptionKey } from './get-data-encryption-key.js'\n\nconst ALGORITHM = 'aes-256-cbc'\nconst IV_LENGTH = 16\n\n/**\n * What this writes: `<iv as hex>:<ciphertext as hex>`. The IV is 16 bytes, so the prefix is\n * exactly 32 hex characters, and the body is hex of even length.\n *\n * Reading matches on that shape rather than trying and seeing what happens, because the two\n * failures below have to stay apart.\n */\nconst CIPHERTEXT = /^[0-9a-f]{32}:(?:[0-9a-f]{2})+$/\n\n/**\n * Encrypting a database column, and reading one that may not be encrypted yet.\n *\n * ── Reading tells two failures apart ────────────────────────────────────────\n * This used to answer `null` whenever decryption threw, which folded two very different\n * things into one:\n *\n *     the value was written before this column was encrypted   →  it is plaintext\n *     the value is ciphertext and the key cannot open it       →  something is wrong\n *\n * Both came back as \"there is no value\". A deployment with the wrong `dataEncryptionKey`\n * therefore looked like a system holding no credentials at all — the rows were intact, one\n * line went to the console, and nothing said which row or how many. Devices kept\n * authenticating, because a signed token never consults these columns, so only the screens\n * lost the values.\n *\n * So: a value that is not ciphertext-shaped is returned as it is, which is what lets a column\n * be encrypted without a flag day. A value that IS ciphertext-shaped and will not open throws,\n * because that is a broken key and not an absent value.\n */\nexport const encryptTransformer: ValueTransformer = {\n  to: (entityValue: string) => encrypt(entityValue),\n  from: (databaseValue: string) => decrypt(databaseValue)\n}\n\n/** Raised when a value is ciphertext and the configured key does not open it. */\nexport class DecryptionFailed extends Error {\n  constructor(cause: unknown) {\n    super(\n      'an encrypted column could not be decrypted with the configured dataEncryptionKey. ' +\n        'The value is still in the database — this is a key problem, not a missing value.'\n    )\n\n    this.name = 'DecryptionFailed'\n    ;(this as any).cause = cause\n  }\n}\n\nfunction encrypt(text: string): string {\n  if (!text) {\n    return null\n  }\n\n  const iv = randomBytes(IV_LENGTH)\n  const cipher = createCipheriv(ALGORITHM, dataEncryptionKey, iv)\n  const encrypted = Buffer.concat([cipher.update(text, 'utf8'), cipher.final()])\n\n  return `${iv.toString('hex')}:${encrypted.toString('hex')}`\n}\n\nfunction decrypt(text: string): string {\n  if (!text) {\n    return null\n  }\n\n  /*\n   * Written before this column was encrypted. Handing it back unchanged is the whole of the\n   * backward compatibility: a column can start encrypting while the rows already in it stay\n   * readable, and each row converts the next time something writes it.\n   */\n  if (!CIPHERTEXT.test(text)) {\n    return text\n  }\n\n  try {\n    const [ivHex, bodyHex] = text.split(':')\n    const decipher = createDecipheriv(ALGORITHM, dataEncryptionKey, Buffer.from(ivHex, 'hex'))\n\n    return Buffer.concat([decipher.update(Buffer.from(bodyHex, 'hex')), decipher.final()]).toString('utf8')\n  } catch (err) {\n    throw new DecryptionFailed(err)\n  }\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/shell",
-  "version": "10.1.29",
+  "version": "10.1.33",
   "description": "Core module for framework",
   "bin": {
     "things-factory": "bin/things-factory",
@@ -126,5 +126,5 @@
     "pg": "^8.7.3",
     "sqlite3": "^5.0.8"
   },
-  "gitHead": "e6bf9dec003fe5e794746aaeb5852b3b50478232"
+  "gitHead": "7fb7b6587846b5ff6ee7a4983652d9561b4d6b2c"
 }

package/tests/encrypt-transform.test.ts

@@ -0,0 +1,130 @@
+import { encryptTransformer, DecryptionFailed } from '../server/typeorm/encrypt-transform'
+
+/**
+ * Reading an encrypted column has to tell two failures apart.
+ *
+ * The transformer used to answer `null` whenever decryption threw. That folded together a value
+ * written before the column was encrypted (plaintext, perfectly fine) and a value that is
+ * ciphertext the key will not open (something is wrong). Both read as "there is no value", so a
+ * deployment with the wrong `dataEncryptionKey` looked like a system holding no credentials —
+ * rows intact, one line on the console, no row named and no count.
+ *
+ * It also blocked turning encryption on at all: every row written before the change would have
+ * gone blank on the next read.
+ */
+
+/** The shape `to` writes: 32 hex characters of IV, a colon, then hex of even length. */
+const CIPHERTEXT = /^[0-9a-f]{32}:(?:[0-9a-f]{2})+$/
+
+describe('writing an encrypted column', () => {
+  it('produces the iv:body shape', () => {
+    const stored = encryptTransformer.to('client-secret-value')
+
+    expect(stored).toMatch(CIPHERTEXT)
+    expect(stored).not.toContain('client-secret-value')
+  })
+
+  it('keeps nothing for an empty value', () => {
+    expect(encryptTransformer.to('')).toBeNull()
+    expect(encryptTransformer.to(null as any)).toBeNull()
+  })
+
+  it('writes a different string each time, so equal values do not look equal at rest', () => {
+    /* The IV is random per write. Without that, two rows holding the same secret would match. */
+    expect(encryptTransformer.to('same')).not.toEqual(encryptTransformer.to('same'))
+  })
+})
+
+describe('reading an encrypted column', () => {
+  it('round-trips what it wrote', () => {
+    expect(encryptTransformer.from(encryptTransformer.to('client-secret-value'))).toEqual('client-secret-value')
+  })
+
+  it('hands back a value written before the column was encrypted', () => {
+    /*
+     * ⚠ The case that makes turning encryption on possible at all. Every row already in the
+     * table is plaintext; if reading them answered null they would go blank on deploy.
+     */
+    expect(encryptTransformer.from('plain-client-secret')).toEqual('plain-client-secret')
+  })
+
+  it('hands back a JWT, which is what these columns actually hold', () => {
+    /*
+     * `Appliance.accessToken` and the shadow user's password hold signed JWTs. A JWT is dot
+     * separated and carries no colon, so it can never be mistaken for the ciphertext shape.
+     */
+    const token = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjEyMyIsInVzZXJUeXBlIjoiYXBwbGlhbmNlIn0.c2lnbmF0dXJl'
+
+    expect(encryptTransformer.from(token)).toEqual(token)
+  })
+
+  it('throws when the value is ciphertext and the key does not open it', () => {
+    /*
+     * ⚠ The case this file exists for. Answering null here is what made a wrong key look like an
+     * empty system. The row is still there; what is broken is the key.
+     */
+    const iv = 'a'.repeat(32)
+    const body = 'b'.repeat(64)
+
+    expect(() => encryptTransformer.from(`${iv}:${body}`)).toThrow(DecryptionFailed)
+  })
+
+  it('says in the message that the value still exists', () => {
+    /* Whoever reads the log has to know not to go re-issue credentials. */
+    const iv = 'a'.repeat(32)
+
+    expect(() => encryptTransformer.from(`${iv}:${'b'.repeat(64)}`)).toThrow(/still in the database/)
+  })
+
+  it('keeps nothing for an empty value', () => {
+    expect(encryptTransformer.from('')).toBeNull()
+    expect(encryptTransformer.from(null as any)).toBeNull()
+  })
+})
+
+describe('telling the two shapes apart', () => {
+  /*
+   * The split has to be exact in both directions: a plaintext value read as ciphertext throws on
+   * a perfectly good row, and a ciphertext value read as plaintext hands out the stored bytes.
+   */
+
+  it('does not take a colon alone for ciphertext', () => {
+    expect(encryptTransformer.from('host:5432')).toEqual('host:5432')
+    expect(encryptTransformer.from('Basic dXNlcjpwYXNz')).toEqual('Basic dXNlcjpwYXNz')
+  })
+
+  it('does not take hex of the wrong length for ciphertext', () => {
+    /* The IV is 16 bytes, so 32 hex characters and no other length. */
+    expect(encryptTransformer.from(`${'a'.repeat(31)}:${'b'.repeat(64)}`)).toEqual(
+      `${'a'.repeat(31)}:${'b'.repeat(64)}`
+    )
+    expect(encryptTransformer.from(`${'a'.repeat(33)}:${'b'.repeat(64)}`)).toEqual(
+      `${'a'.repeat(33)}:${'b'.repeat(64)}`
+    )
+  })
+
+  it('does not take an odd-length body for ciphertext', () => {
+    const odd = `${'a'.repeat(32)}:${'b'.repeat(63)}`
+
+    expect(encryptTransformer.from(odd)).toEqual(odd)
+  })
+
+  it('does not take uppercase hex for ciphertext', () => {
+    /* `to` writes lowercase. Something else wrote this, so it is not ours to decrypt. */
+    const upper = `${'A'.repeat(32)}:${'B'.repeat(64)}`
+
+    expect(encryptTransformer.from(upper)).toEqual(upper)
+  })
+
+  it('recognises its own output as ciphertext', () => {
+    /*
+     * The other direction of the same split, and the one that would silently hand out stored
+     * bytes if the pattern ever stopped matching what `to` writes.
+     */
+    const stored = encryptTransformer.to('secret')
+
+    expect(stored).toMatch(CIPHERTEXT)
+    expect(encryptTransformer.from(stored)).toEqual('secret')
+    expect(encryptTransformer.from(stored)).not.toEqual(stored)
+  })
+})

package/tests/md-sys-slot-owners.test.ts

@@ -12,11 +12,11 @@
  * compute time, so bundle order stops mattering, and a slot that is not opened cannot be reached.
  *
  * Three owners, one mechanism - no reliance on bundle order or specificity:
- *   --brand-<slot>   a product's accent (its own brand.css)                26 slots
+ *   --brand-<slot>   a product's accent (its own <product>-accent.css)     26 slots
  *   --suite-<slot>   the operato suite's shared greys (@things-factory/operato-suite)  17 slots
  *   closed           error x4, shadow, scrim - literal, nobody above the platform sets them  6 slots
  * A tenant's domain theme still wins over all of these: it writes --md-sys-color-* directly, later in
- * the bundle. Apps with neither brand.css nor the suite get the fallbacks, the shell values of before.
+ * the bundle. Apps with neither an accent file nor the suite get the fallbacks, the shell values of before.
  *
  * If md adds a slot the counts go red on purpose: someone has to decide whose it is.
  */

package/tests/refusal.test.ts

@@ -0,0 +1,63 @@
+/**
+ * A refusal keeps its name on the way out, and gets its sentence from the caller's language.
+ *
+ * ── Why these four ────────────────────────────────────────────────────────
+ * The code is the contract (ADR-0042): a client reads `extensions.refusal.code` and decides what to
+ * show. If Apollo's own `code` were left empty it would read `INTERNAL_SERVER_ERROR`, and a refusal
+ * would look like a crash. If `t` were called without params the locale would be lost and a Korean
+ * reader would get English with no error anywhere. If a module has not declared the key, the English
+ * sentence has to win over the key printed raw.
+ *
+ * Moved here from operato-plant when worklist became the third consumer (ADR-0069 decision 3).
+ */
+
+import { GraphQLError } from 'graphql'
+
+import { Refusal, refusalKey, rethrowSpoken, speakRefusal } from '../server/refusal/refusal.js'
+
+const refusal = () => new Refusal('approval-line-missing', { role: 'quality' }, 'no approval line stands for quality.')
+
+describe('a refusal on the way out', () => {
+  it('carries its own name, and says the server refused on purpose', () => {
+    const error = speakRefusal(refusal(), {})
+
+    expect(error).toBeInstanceOf(GraphQLError)
+    expect(error.extensions.code).toBe('BAD_USER_INPUT')
+    expect(error.extensions.refusal).toEqual({ code: 'approval-line-missing', params: { role: 'quality' } })
+  })
+
+  it('asks for error.<code> and hands the values over, never undefined', () => {
+    const asked: Array<{ key: string; options?: Record<string, unknown> }> = []
+    const t = (key: string, options?: Record<string, unknown>) => {
+      asked.push({ key, options })
+      return '품질 결재선이 비어 있습니다.'
+    }
+
+    const error = speakRefusal(refusal(), { t })
+
+    expect(asked).toHaveLength(1)
+    expect(asked[0].key).toBe(refusalKey('approval-line-missing'))
+    /* `t(key, undefined)` answers in English however the request came in, so the values always travel. */
+    expect(asked[0].options).toEqual({ role: 'quality', defaultValue: 'no approval line stands for quality.' })
+    expect(error.message).toBe('품질 결재선이 비어 있습니다.')
+  })
+
+  it('reads as English when the module has not declared the key', () => {
+    /* i18next answers with defaultValue when the key is missing; a missing key must not print itself. */
+    const t = (_key: string, options?: Record<string, unknown>) => String(options?.defaultValue ?? _key)
+
+    expect(speakRefusal(refusal(), { t }).message).toBe('no approval line stands for quality.')
+  })
+})
+
+describe('rethrowSpoken', () => {
+  it('speaks a refusal', () => {
+    expect(() => rethrowSpoken(refusal(), {})).toThrow(GraphQLError)
+  })
+
+  it('leaves anything else exactly as it was - a crash is not a refusal', () => {
+    const crash = new TypeError('cannot read properties of undefined')
+
+    expect(() => rethrowSpoken(crash, {})).toThrow(crash)
+  })
+})

package/tests/theme-file-names.test.ts

@@ -0,0 +1,90 @@
+/**
+ * A theme file carries its owner's name - `themes/` is one namespace shared by every module.
+ *
+ * The builder's ThemeOverridePlugin collects `client/themes/*.css` from every module and keeps the
+ * FIRST file it meets for each file name, application first (webpack-plugins/theme-override-plugin.js).
+ * It never looks inside. So a module that ships `light.css` replaces the shell's `light.css` whole -
+ * including the 49 slots the shell opens as `var(--brand-*)` / `var(--suite-*)`, and including any
+ * fix made there later. A file with one declaration in it does that just as completely as a full
+ * palette.
+ *
+ * Hence the rule (ADR-0060 decision 2-1): inside things-factory only the shell carries the names of
+ * the shell's theme files. A product that means to replace one of them wholesale may still do it -
+ * that is what an application's own light.css was - but then it owns all 49 slots and stops
+ * receiving anything the platform decides.
+ *
+ * The exceptions below are named, with what has to happen for each to go. When one is dealt with
+ * this test goes red and the line gets deleted - that is the point of listing them rather than
+ * filtering them out.
+ */
+
+import { readdirSync, existsSync } from 'fs'
+import path from 'path'
+
+const PACKAGES = path.resolve(__dirname, '..', '..')
+const SHELL_THEMES = path.resolve(__dirname, '..', 'client', 'themes')
+
+/**
+ * Files that carry a shell theme file's name today.
+ *
+ * - The generator templates are copied into a new application, so a new product is born replacing
+ *   the shell theme - operato-warehouse was born that way. They are fixed once the four operato
+ *   products have moved.
+ */
+const KNOWN: string[] = [
+  'generator/templates/app/client/themes/dark.css',
+  'generator/templates/app/client/themes/light.css',
+  'generator/templates/brand/client/themes/dark.css',
+  'generator/templates/brand/client/themes/light.css'
+]
+
+/** Every `client/themes/*.css` under packages, as a path relative to packages. */
+function themeFiles(): string[] {
+  const found: string[] = []
+
+  const walk = (dir: string) => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      if (entry.name === 'node_modules' || entry.name.startsWith('.') || entry.name.startsWith('dist')) {
+        continue
+      }
+
+      const full = path.join(dir, entry.name)
+
+      if (entry.isDirectory()) {
+        walk(full)
+      } else if (entry.name.endsWith('.css') && path.basename(path.dirname(full)) === 'themes') {
+        if (path.basename(path.dirname(path.dirname(full))) === 'client') {
+          found.push(path.relative(PACKAGES, full))
+        }
+      }
+    }
+  }
+
+  walk(PACKAGES)
+
+  return found.sort()
+}
+
+describe('theme file names', () => {
+  it('finds the theme files at all - an empty scan would pass everything below', () => {
+    const files = themeFiles()
+
+    expect(files.length).toBeGreaterThan(20)
+    expect(files).toContain(path.join('shell', 'client', 'themes', 'light.css'))
+  })
+
+  it('only the shell carries the names of the shell theme files', () => {
+    const shellNames = new Set(readdirSync(SHELL_THEMES))
+    const collisions = themeFiles().filter(
+      file => !file.startsWith(`shell${path.sep}`) && shellNames.has(path.basename(file))
+    )
+
+    expect(collisions).toEqual(KNOWN.map(file => file.split('/').join(path.sep)))
+  })
+
+  it('every exception still exists - a stale line hides the next collision', () => {
+    for (const file of KNOWN) {
+      expect(existsSync(path.join(PACKAGES, file.split('/').join(path.sep)))).toBe(true)
+    }
+  })
+})