feat: Add Polybius cipher

Author: TheAlexLichter

README.md

@@ -79,6 +79,7 @@ document.getElementById("t").innerHTML = this["cipher-collection"].wolfenbuettel
 - Affine
 - AER-256
 - ARMON-64
+- Polybius
 
 ## 📖 Documentation
 

docs/ciphers/polybius.md

@@ -0,0 +1,145 @@
+# Polybius
+
+> The Polybius cipher, named by a greek philosopher, utilizes a 5x5 square
+  (or 6x6 with numbers) called *Polybius square* to encrypt and decrypt messages.
+  It contains the cipher alphabet, modified by the key (distinct letters of the key
+  first, then the rest of the alphabet).
+
+## Cipher behavior information
+
+* Case sensitive? ❌
+* Deterministic? ✓
+* Alphabet: A-Z, numbers optionally
+* Characters not in alphabet will be: **omitted**, **preserved**, **throw an error (default)**
+
+## Default options object
+
+```
+const options = {
+  key: '', // Custom key containing only cipher alphabet characters (duplicates allowed)
+  withNumbers: false, // Use numbers as well (increases square size from 5 to 6)
+  equalLetters: 'IJ', // Two letters used for substitution
+  failOnUnknownCharacter: true, // Throw an error on unknown characters
+  omitUnknownCharacter: true // If no error should be thrown, omit character?
+}
+```
+
+**ATTENTION**: The `equalLetters` option will only be used when `withNumbers` is set to false.
+The second character set will be substituted with the first one (default: J will become I).
+This is necessary because a 5x5 square can only bear 25 characters.
+
+## Usage
+
+### Encoding
+
+#### Default
+
+```
+import { polybius } from 'cipher-collection'
+
+
+console.log(polybius.encode('AB')) // 11 12
+console.log(polybius.encode('a')) // 11
+```
+
+#### Custom key
+
+```
+import { polybius } from 'cipher-collection'
+
+
+console.log(polybius.encode('Ac', { key: 'cakeIsLie' })) // 12 11
+```
+
+#### Custom substitution
+
+```
+import { polybius } from 'cipher-collection'
+
+
+console.log(polybius.encode('IJ')) // 24 24
+console.log(polybius.encode('UV', { equalLetters: 'UV' })) // 51 51
+```
+
+
+
+#### With numbers
+
+```
+import { polybius } from 'cipher-collection'
+
+
+console.log(polybius.encode('Ac012', { withNumbers: true })) // 11 13 53 54 55
+
+// No substitution anymore!
+console.log(polybius.encode('IJ')) // 23 24
+```
+
+
+#### Error handling
+
+```
+import { polybius } from 'cipher-collection'
+
+console.log(polybius.encode('N*') // Error: Unknown character *
+console.log(polybius.encode('N*', { failOnUnknownCharacter: false })) // 33
+console.log(polybius.encode('N* ', { failOnUnknownCharacter: false, omitUnknownCharacter: false })) // 33 *
+```
+
+
+### Decoding
+
+#### Default
+
+```
+import { polybius } from 'cipher-collection'
+
+
+console.log(polybius.decode('11 12')) // AB
+```
+
+#### Custom key
+
+```
+import { polybius } from 'cipher-collection'
+
+
+console.log(polybius.decode('12 11', { key: 'cakeIsLie' })) // AC
+```
+
+#### Custom substitution
+
+```
+import { polybius } from 'cipher-collection'
+
+
+console.log(polybius.decode('24 24')) // I I
+console.log(polybius.decode('51', { equalLetters: 'UV' })) // U
+console.log(polybius.decode('51', { equalLetters: 'VU' })) // V
+```
+
+
+
+#### With numbers
+
+```
+import { polybius } from 'cipher-collection'
+
+
+console.log(polybius.decode('11 13 53 54 55', { withNumbers: true })) // AC012
+
+// No substitution anymore!
+console.log(polybius.decode('23 24')) // IJ
+```
+
+
+#### Error handling
+
+```
+import { polybius } from 'cipher-collection'
+
+console.log(polybius.decode('33*') // Error: Unknown character *
+console.log(polybius.decode('33*', { failOnUnknownCharacter: false })) // N
+console.log(polybius.decode('33* ', { failOnUnknownCharacter: false, omitUnknownCharacter: false })) // N *
+```
+

docs/index.md

@@ -20,3 +20,4 @@
 * [Affine](./ciphers/affine.md)
 * [AER-256](./ciphers/aer256.md)
 * [ARMON-64](./ciphers/armon64.md)
+* [Polybius](./ciphers/polybius.md)

src/helpers/index.js

@@ -8,6 +8,13 @@ export const randomInRange = (min, max) => {
   return Math.floor(Math.random() * (max - min)) + min
 }
 
+/**
+ * Throw an error or return an empty string silently
+ * @param {object} options Object that **must** include a property called `failOnUnknownCharacter` which determines
+ * if an error will be thrown or not
+ * @param {string} errorMessage The error message that will be possibly used
+ * @returns {string}
+ */
 export const throwOrSilent = (options, errorMessage) => {
   if (options.failOnUnknownCharacter) {
     throw Error(errorMessage)

src/index.js

@@ -10,6 +10,7 @@ import multiplicative from './multiplicative'
 import affine from './affine'
 import aer256 from './aer256'
 import armon64 from './armon64'
+import polybius from './polybius'
 
 export default {
   rot,
@@ -23,5 +24,6 @@ export default {
   multiplicative,
   affine,
   aer256,
-  armon64
+  armon64,
+  polybius
 }

src/polybius.js

@@ -0,0 +1,83 @@
+import { throwOrSilent } from './helpers'
+
+const encode = (input, options = {}) => {
+  options = { ...DEFAULT_OPTIONS, ...options }
+
+  const grid = prepareGridString(options)
+  let squareSize = 6
+
+  if (!options.withNumbers) {
+    const [substitute, toReplace] = [...options.equalLetters]
+    input = input.replace(new RegExp(toReplace, 'gi'), substitute)
+
+    squareSize = 5
+  }
+  return [...input.toUpperCase()].map(c => {
+    /*
+     * Think of a grid string as a real grid with 5^2 places:
+     *
+     * - 1 2 3 4 5
+     * 1 A B C D E
+     * 2 F G H I K
+     * 3 L M N O P
+     * 4 Q R S T U
+     * 5 V W X Y Z
+     *
+     * Now map letters to the corresponding row and col
+     */
+
+    const characterIndex = grid.indexOf(c)
+    const row = Math.ceil((characterIndex + 1) / squareSize)
+    const col = (characterIndex % squareSize) + 1
+
+    if ([row, col].includes(0)) {
+      return errorExpression(c, options)
+    }
+
+    return `${row}${col}`
+  }).filter(c => c.length).join(' ')
+}
+
+const decode = (input, options = {}) => {
+  options = { ...DEFAULT_OPTIONS, ...options }
+
+  const grid = prepareGridString(options)
+  let squareSize = options.withNumbers ? 6 : 5
+
+  return input.split(' ')
+    .map(sequence => {
+      if (!sequence.match(/\d{2}/)) {
+        return errorExpression(sequence, options)
+      }
+      const [row, col] = sequence
+
+      return grid.charAt(squareSize * (row - 1) + (col - 1)) || errorExpression(sequence, options)
+    }).join('')
+}
+
+const errorExpression = (c, options) => throwOrSilent(options, `Unknown character ${c}`) || options.omitUnknownCharacter ? '' : c
+
+const DEFAULT_OPTIONS = {
+  key: '',
+  equalLetters: 'IJ',
+  withNumbers: false,
+  failOnUnknownCharacter: true,
+  omitUnknownCharacter: true
+}
+
+const prepareGridString = options =>
+  [...options.key.toUpperCase(), ...getAlphabet(options)].reduce((acc, letter) => {
+    return !acc.includes(letter) ? acc.concat(letter) : acc
+  })
+
+const getAlphabet = options => {
+  const [substitute, toReplace] = [...options.equalLetters]
+  const alphabet = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'
+
+  return options.withNumbers ? `${alphabet}0123456789` : alphabet.replace(toReplace, substitute)
+}
+
+export default {
+  encode,
+  decode
+}

test/polybius.test.js

@@ -0,0 +1,88 @@
+import polybius from 'polybius'
+
+describe('encoding', () => {
+  test('default', () => {
+    expect(polybius.encode('ABCDEFGHIJKLMNOPQRSTUVWXYZ')).toBe('11 12 13 14 15 21 22 23 24 24 25 31 32 33 34 35 41 42' +
+      ' 43 44 45 51 52 53 54 55')
+    expect(polybius.encode('ABCDEFGHIJKLMNOPQRSTUVWXYZ'.toLowerCase())).toBe('11 12 13 14 15 21 22 23 24 24 25 31 32 33 34 35' +
+      ' 41 42' +
+      ' 43 44 45 51 52 53 54 55')
+  })
+  test('default with illegal character', () => {
+    expect(() => { polybius.encode('*') }).toThrowError('Unknown character *')
+  })
+
+  test('with custom key', () => {
+    expect(polybius.encode('ABCDEFGHIJKLMNOPQRSTUVWXYZ', { key: 'OHA' }))
+      .toBe('13 14 15 21 22 23 24 12 25 25 31 32 33 34 11 35 41 42 43 44 45 51 52 53 54 55')
+    expect(polybius.encode('ABCDEFGHIJKLMNOPQRSTUVWXYZ', { key: 'oHa' }))
+      .toBe('13 14 15 21 22 23 24 12 25 25 31 32 33 34 11 35 41 42 43 44 45 51 52 53 54 55')
+  })
+
+  test('with numbers', () => {
+    expect(polybius.encode('ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789', { withNumbers: true }))
+      .toBe('11 12 13 14 15 16 21 22 23 24 25 26 31 32 33 34 35 36 41 42 43 44 45 46 51 52 53 54 55 56 61 62 63 64' +
+        ' 65 66')
+  })
+
+  test('with numbers and custom key', () => {
+    expect(polybius.encode('ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789', { withNumbers: true, key: 'oHa' }))
+      .toBe('13 14 15 16 21 22 23 12 24 25 26 31 32 33 11 34 35 36 41 42 43 44 45 46 51 52 53 54 55 56 61 62 63 64 65 66')
+  })
+
+  test('with custom substitution', () => {
+    expect(polybius.encode('ABCDEFGHIJKLMNOPQRSTUVWXYZ', { equalLetters: 'UV' }))
+      .toBe('11 12 13 14 15 21 22 23 24 25 31 32 33 34 35 41 42 43 44 45 51 51 52 53 54 55')
+  })
+
+  test('omit illegal character', () => {
+    expect(polybius.encode('N*', { failOnUnknownCharacter: false })).toBe('33')
+  })
+
+  test('preserve illegal character', () => {
+    expect(polybius.encode('N* ', { failOnUnknownCharacter: false, omitUnknownCharacter: false })).toBe('33 *  ')
+  })
+})
+
+describe('decoding', () => {
+  test('default', () => {
+    expect(polybius.decode('11 12 13 14 15 21 22 23 24 24 25 31 32 33 34 35 41 42 43 44 45 51 52 53 54 55')).toBe('ABCDEFGHIIKLMNOPQRSTUVWXYZ')
+  })
+  test('default with illegal character', () => {
+    expect(() => { polybius.decode('*') }).toThrowError('Unknown character *')
+    expect(() => { polybius.decode('88') }).toThrowError('Unknown character 88')
+  })
+
+  test('with custom key', () => {
+    expect(polybius.decode('13 14 15 21 22 23 24 12 25 25 31 32 33 34 11 35 41 42 43 44 45 51 52 53 54 55', { key: 'OHA' }))
+      .toBe('ABCDEFGHIIKLMNOPQRSTUVWXYZ')
+    expect(polybius.decode('13 14 15 21 22 23 24 12 25 25 31 32 33 34 11 35 41 42 43 44 45 51 52 53 54 55', { key: 'oHa' }))
+      .toBe('ABCDEFGHIIKLMNOPQRSTUVWXYZ')
+  })
+
+  test('with numbers', () => {
+    expect(polybius.decode('11 12 13 14 15 16 21 22 23 24 25 26 31 32 33 34 35 36 41 42 43 44 45 46 51 52 53 54 55 56 61 62 63 64 65 66', { withNumbers: true }))
+      .toBe('ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789')
+  })
+
+  test('with numbers and custom key', () => {
+    expect(polybius.decode('13 14 15 16 21 22 23 12 24 25 26 31 32 33 11 34 35 36 41 42 43 44 45 46 51 52 53 54 55' +
+      ' 56 61 62 63 64 65 66', { withNumbers: true, key: 'oHa' }))
+      .toBe('ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789')
+  })
+
+  test('with custom substitution', () => {
+    expect(polybius.decode('11 12 13 14 15 21 22 23 24 25 31 32 33 34 35 41 42 43 44 45 51 51 52 53 54 55', { equalLetters: 'UV' }))
+      .toBe('ABCDEFGHIJKLMNOPQRSTUUWXYZ')
+    expect(polybius.decode('11 12 13 14 15 21 22 23 24 25 31 32 33 34 35 41 42 43 44 45 51 51 52 53 54 55', { equalLetters: 'VU' }))
+      .toBe('ABCDEFGHIJKLMNOPQRSTVVWXYZ')
+  })
+
+  test('omit illegal character', () => {
+    expect(polybius.decode('33 *', { failOnUnknownCharacter: false })).toBe('N')
+  })
+
+  test('preserve illegal character', () => {
+    expect(polybius.decode('33 *', { failOnUnknownCharacter: false, omitUnknownCharacter: false })).toBe('N*')
+  })
+})