@things-factory/shell 10.1.31 → 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.31",
+  "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": "5213e6f9913b40ea2618a2111d9884b792dbaa01"
+  "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)
+  })
+})