expo-secure-keypad-jsi 0.1.0

package/build/SecureKeypadJsiView.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SecureKeypadJsiView.d.ts","sourceRoot":"","sources":["../src/SecureKeypadJsiView.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,OAAO,KAAK,EAAE,kBAAkB,EAAE,wBAAwB,EAAE,MAAM,yBAAyB,CAAC;AAM5F,mDAAmD;AACnD,QAAA,MAAM,mBAAmB,qGAIxB,CAAC;AAIF,eAAe,mBAAmB,CAAC"}

package/build/SecureKeypadJsiView.js

@@ -0,0 +1,10 @@
+import { requireNativeView } from 'expo';
+import * as React from 'react';
+const NativeView = requireNativeView('SecureKeypadJsi');
+/** Most apps should use `SecureKeypad` instead. */
+const SecureKeypadJsiView = React.forwardRef((props, ref) => {
+    return <NativeView {...props} ref={ref}/>;
+});
+SecureKeypadJsiView.displayName = 'SecureKeypadJsiView';
+export default SecureKeypadJsiView;
+//# sourceMappingURL=SecureKeypadJsiView.js.map

package/build/SecureKeypadJsiView.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SecureKeypadJsiView.js","sourceRoot":"","sources":["../src/SecureKeypadJsiView.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAC;AACzC,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAI/B,MAAM,UAAU,GAEZ,iBAAiB,CAAC,iBAAiB,CAAC,CAAC;AAEzC,mDAAmD;AACnD,MAAM,mBAAmB,GAAG,KAAK,CAAC,UAAU,CAC1C,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE;IACb,OAAO,CAAC,UAAU,CAAC,IAAI,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,EAAG,CAAC;AAC7C,CAAC,CACF,CAAC;AAEF,mBAAmB,CAAC,WAAW,GAAG,qBAAqB,CAAC;AAExD,eAAe,mBAAmB,CAAC","sourcesContent":["import { requireNativeView } from 'expo';\nimport * as React from 'react';\n\nimport type { SecureKeypadHandle, SecureKeypadJsiViewProps } from './SecureKeypadJsi.types';\n\nconst NativeView: React.ComponentType<\n  SecureKeypadJsiViewProps & { ref?: React.Ref<SecureKeypadHandle> }\n> = requireNativeView('SecureKeypadJsi');\n\n/** Most apps should use `SecureKeypad` instead. */\nconst SecureKeypadJsiView = React.forwardRef<SecureKeypadHandle, SecureKeypadJsiViewProps>(\n  (props, ref) => {\n    return <NativeView {...props} ref={ref} />;\n  }\n);\n\nSecureKeypadJsiView.displayName = 'SecureKeypadJsiView';\n\nexport default SecureKeypadJsiView;\n"]}

package/build/index.d.ts

@@ -0,0 +1,5 @@
+export { default as SecureKeypad } from './SecureKeypad';
+export type { SecureKeypadProps } from './SecureKeypad';
+export { default as SecureKeypadJsiView } from './SecureKeypadJsiView';
+export * from './SecureKeypadJsi.types';
+//# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACzD,YAAY,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAExD,OAAO,EAAE,OAAO,IAAI,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAEvE,cAAc,yBAAyB,CAAC"}

package/build/index.js

@@ -0,0 +1,5 @@
+// PIN digits never enter the JS runtime — see README for the threat model.
+export { default as SecureKeypad } from './SecureKeypad';
+export { default as SecureKeypadJsiView } from './SecureKeypadJsiView';
+export * from './SecureKeypadJsi.types';
+//# sourceMappingURL=index.js.map

package/build/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAE3E,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAGzD,OAAO,EAAE,OAAO,IAAI,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAEvE,cAAc,yBAAyB,CAAC","sourcesContent":["// PIN digits never enter the JS runtime — see README for the threat model.\n\nexport { default as SecureKeypad } from './SecureKeypad';\nexport type { SecureKeypadProps } from './SecureKeypad';\n\nexport { default as SecureKeypadJsiView } from './SecureKeypadJsiView';\n\nexport * from './SecureKeypadJsi.types';\n"]}

package/common/CMakeLists.txt

@@ -0,0 +1,49 @@
+# Copyright (c) 2026 expo-secure-keypad-jsi contributors. MIT License.
+#
+# Reusable static library `esk_core` holding the platform-agnostic security
+# core. Consumed by android/CMakeLists.txt (with prefab OpenSSL) and by
+# tests/cpp/CMakeLists.txt (with host OpenSSL).
+#
+# The caller must provide the OpenSSL crypto target name via ESK_OPENSSL_TARGET
+# before add_subdirectory():
+#   * host / CI:   OpenSSL::Crypto   (find_package(OpenSSL))
+#   * Android:     openssl::crypto   (prefab from the openssl-static AAR)
+
+cmake_minimum_required(VERSION 3.22)
+project(esk_core LANGUAGES CXX)
+
+if(NOT DEFINED ESK_OPENSSL_TARGET)
+  set(ESK_OPENSSL_TARGET OpenSSL::Crypto)
+endif()
+
+# Listed explicitly, not globbed: a glob is cached at configure time, so adding
+# or deleting a file leaves stale entries in an incremental NDK build.
+set(ESK_CORE_SOURCES
+  src/Base64.cpp
+  src/Error.cpp
+  src/KeypadCore.cpp
+  src/PinEncryptor.cpp
+  src/PublicKeyValidator.cpp
+  src/SecureBuffer.cpp
+  src/SecureRandom.cpp
+  src/esk_c_api.cpp)
+list(TRANSFORM ESK_CORE_SOURCES PREPEND "${CMAKE_CURRENT_SOURCE_DIR}/")
+
+add_library(esk_core STATIC ${ESK_CORE_SOURCES})
+
+target_include_directories(esk_core PUBLIC
+  "${CMAKE_CURRENT_SOURCE_DIR}/include")
+
+target_compile_features(esk_core PUBLIC cxx_std_20)
+
+set_target_properties(esk_core PROPERTIES
+  CXX_STANDARD 20
+  CXX_STANDARD_REQUIRED ON
+  CXX_EXTENSIONS OFF
+  POSITION_INDEPENDENT_CODE ON)
+
+target_compile_options(esk_core PRIVATE
+  -Wall -Wextra -Wpedantic
+  $<$<CONFIG:Release>:-O2>)
+
+target_link_libraries(esk_core PUBLIC ${ESK_OPENSSL_TARGET})

package/common/include/esk/Base64.h

@@ -0,0 +1,20 @@
+// Copyright (c) 2026 expo-secure-keypad-jsi contributors. MIT License.
+#pragma once
+
+#include <cstddef>
+#include <cstdint>
+#include <string>
+
+namespace esk {
+namespace base64 {
+
+// Standard base64 (with padding) encode. Used only for ciphertext/nonce, which
+// are not secret, so no constant-time requirement here.
+std::string encode(const uint8_t* data, size_t len);
+
+// Decode standard base64. Returns false on malformed input. Used by the host
+// test suite's reference decryptor; the runtime paths only ever encode.
+bool decode(const std::string& in, std::string& out);
+
+}  // namespace base64
+}  // namespace esk

package/common/include/esk/Cleanse.h

@@ -0,0 +1,17 @@
+// Copyright (c) 2026 expo-secure-keypad-jsi contributors. MIT License.
+#pragma once
+
+#include <cstddef>
+#include <openssl/crypto.h>
+
+namespace esk {
+
+// Never memset() plaintext: the compiler is allowed to elide it, OPENSSL_cleanse
+// is not.
+inline void cleanse(void* ptr, size_t len) {
+  if (ptr != nullptr && len > 0) {
+    OPENSSL_cleanse(ptr, len);
+  }
+}
+
+}  // namespace esk

package/common/include/esk/Error.h

@@ -0,0 +1,37 @@
+// Copyright (c) 2026 expo-secure-keypad-jsi contributors. MIT License.
+#pragma once
+
+#include <stdexcept>
+#include <string>
+
+namespace esk {
+
+// Reaches JS as the "ERR_..." strings in Error.cpp, so the names are API:
+// renaming one is a breaking change.
+enum class ErrorCode {
+  KeyParse,
+  KeyNotRsa,
+  WeakKey,
+  NotArmed,
+  Empty,       // submit() with no digits
+  TooShort,    // submit() below minLength
+  Encrypt,
+  Random,
+  Internal,
+};
+
+const char* errorCodeName(ErrorCode code);
+
+class EskError : public std::runtime_error {
+ public:
+  EskError(ErrorCode code, const std::string& message)
+      : std::runtime_error(message), code_(code) {}
+
+  ErrorCode code() const noexcept { return code_; }
+  const char* codeName() const noexcept { return errorCodeName(code_); }
+
+ private:
+  ErrorCode code_;
+};
+
+}  // namespace esk

package/common/include/esk/KeypadCore.h

@@ -0,0 +1,69 @@
+// Copyright (c) 2026 expo-secure-keypad-jsi contributors. MIT License.
+#pragma once
+
+#include <array>
+#include <functional>
+#include <memory>
+#include <optional>
+#include <string>
+
+#include "esk/PublicKeyValidator.h"
+#include "esk/SecureBuffer.h"
+
+namespace esk {
+
+enum class KeypadState { Unarmed, Armed };
+
+// Digit = numeric PIN pad, Full = QWERTY keyboard. Same wire format either way.
+enum class KeypadType { Digit, Full };
+
+// Owned by the platform native view. All methods must run on the owning (UI)
+// thread — SecureBuffer enforces this.
+class KeypadCore {
+ public:
+  // nowProvider is injected so the platform owns the clock and tests stay
+  // deterministic. Lengths clamp to [4,12] for Digit and [4,64] for Full.
+  explicit KeypadCore(std::function<int64_t()> nowProvider,
+                      size_t minLength = kMinPinLength,
+                      size_t maxLength = kMaxPinLength,
+                      KeypadType type = KeypadType::Digit);
+  ~KeypadCore();
+
+  KeypadCore(const KeypadCore&) = delete;
+  KeypadCore& operator=(const KeypadCore&) = delete;
+
+  // nullopt on success; otherwise the error-code name (e.g. "ERR_WEAK_KEY").
+  std::optional<std::string> arm(const std::string& publicKeyPem);
+
+  // Return the resulting entered-key count. pressKey takes the final ASCII
+  // character (the view resolves shift/layer state before calling); characters
+  // outside the type's charset are silently ignored.
+  size_t pressDigit(uint8_t digit);
+  size_t pressKey(uint8_t asciiChar);
+  size_t backspace();
+  void clearPin();
+
+  // Encrypts, cleanses the buffer, returns the envelope JSON. Throws EskError
+  // on Empty / TooShort / NotArmed.
+  std::string submit();
+
+  size_t digitCount() const;
+  KeypadState state() const { return state_; }
+  KeypadType type() const { return type_; }
+
+  // The view uses this to place glyphs; the mapping never leaves native code.
+  std::array<uint8_t, 10> shuffledLayout() const;
+
+  void onHostBackground();
+
+ private:
+  SecureBuffer buffer_;
+  std::unique_ptr<PublicKey> key_;
+  std::function<int64_t()> nowProvider_;
+  size_t minLength_;
+  size_t maxLength_;
+  KeypadType type_ = KeypadType::Digit;
+  KeypadState state_ = KeypadState::Unarmed;
+};
+
+}  // namespace esk

package/common/include/esk/PinEncryptor.h

@@ -0,0 +1,39 @@
+// Copyright (c) 2026 expo-secure-keypad-jsi contributors. MIT License.
+#pragma once
+
+#include <cstdint>
+#include <string>
+
+#include "esk/PublicKeyValidator.h"
+#include "esk/SecureBuffer.h"
+
+namespace esk {
+
+// Wire format — servers decode against this, so it cannot change without a
+// version bump. README carries the same table. Both keypad types emit it; the
+// digit pad simply never fills more than 12 of the 64 secret bytes.
+//
+// v2 (96 bytes):
+//   0 2 magic {'S','K'} | 2 1 version | 3 1 secretLength
+//   4 64 secret ASCII, zero-padded | 68 16 nonce | 84 8 unix seconds BE
+//   | 92 4 zero
+namespace payload {
+inline constexpr uint8_t kMagic0 = 'S';
+inline constexpr uint8_t kMagic1 = 'K';
+inline constexpr uint8_t kVersion = 2;
+inline constexpr size_t kSize = 96;
+inline constexpr size_t kOffSecret = 4;
+inline constexpr size_t kNonceSize = 16;
+inline constexpr size_t kOffNonce = 68;
+inline constexpr size_t kOffTimestamp = 84;
+}  // namespace payload
+
+class PinEncryptor {
+ public:
+  // Returns the envelope JSON; throws EskError on failure. Does NOT clear
+  // `buffer` — KeypadCore owns that and cleanses after this returns.
+  static std::string encrypt(const SecureBuffer& buffer, const PublicKey& key,
+                             int64_t nowUnixSeconds);
+};
+
+}  // namespace esk

package/common/include/esk/PublicKeyValidator.h

@@ -0,0 +1,37 @@
+// Copyright (c) 2026 expo-secure-keypad-jsi contributors. MIT License.
+#pragma once
+
+#include <array>
+#include <cstdint>
+#include <memory>
+#include <string>
+
+#include <openssl/evp.h>
+
+namespace esk {
+
+// RAII wrapper over EVP_PKEY. A validated key is the precondition for arming.
+class PublicKey {
+ public:
+  // Enforces: RSA, modulus in [minBits, maxBits], exponent odd and >= 65537.
+  // Throws EskError on any failure.
+  static std::unique_ptr<PublicKey> parse(const std::string& pem,
+                                          int minBits = 2048,
+                                          int maxBits = 8192);
+
+  ~PublicKey();
+  PublicKey(const PublicKey&) = delete;
+  PublicKey& operator=(const PublicKey&) = delete;
+
+  EVP_PKEY* evp() const { return pkey_; }
+
+  // Envelope `kid`: hex of the first 8 bytes of the SPKI SHA-256 digest.
+  std::string keyId() const;
+
+ private:
+  explicit PublicKey(EVP_PKEY* pkey) : pkey_(pkey) {}
+  EVP_PKEY* pkey_ = nullptr;
+  std::array<uint8_t, 32> spkiSha256_{};
+};
+
+}  // namespace esk

package/common/include/esk/SecureBuffer.h

@@ -0,0 +1,60 @@
+// Copyright (c) 2026 expo-secure-keypad-jsi contributors. MIT License.
+#pragma once
+
+#include <cstddef>
+#include <cstdint>
+#include <functional>
+#include <thread>
+
+namespace esk {
+
+// Digit keypad length caps (UI policy; the wire format is shared).
+inline constexpr size_t kMaxPinLength = 12;
+inline constexpr size_t kMinPinLength = 4;
+// Full QWERTY keyboard hard cap and the payload's secret field size. 32 + 64 =
+// 96-byte payload stays well inside the 190-byte RSA-2048 OAEP-SHA256 limit.
+inline constexpr size_t kMaxSecretLength = 64;
+
+// Only printable ASCII (no space) may enter the buffer; anything else is a
+// caller bug, not user input.
+inline constexpr bool isAllowedSecretByte(uint8_t ch) {
+  return ch > 0x20 && ch < 0x7F;
+}
+
+// Secret bytes on a single anonymous mmap'd page — never the heap, where
+// realloc would leave un-cleansable copies. Single-owner (UI) thread, so no
+// locking. Bytes are stored as the final ASCII characters ('0'..'9' for the
+// digit keypad); PinEncryptor copies them into the payload verbatim.
+class SecureBuffer {
+ public:
+  SecureBuffer();
+  ~SecureBuffer();
+
+  SecureBuffer(const SecureBuffer&) = delete;
+  SecureBuffer& operator=(const SecureBuffer&) = delete;
+  SecureBuffer(SecureBuffer&&) = delete;
+  SecureBuffer& operator=(SecureBuffer&&) = delete;
+
+  bool append(uint8_t asciiChar);
+  bool pop();
+  void clear();
+  size_t length() const;
+
+  // The only read path for the plaintext. Pointer is valid for the call only.
+  void withPlaintext(const std::function<void(const uint8_t*, size_t)>& fn) const;
+
+  // True if mlock() succeeded on the page. False means the swap guarantee is
+  // not in effect on this process (low RLIMIT_MEMLOCK); cleanse still runs.
+  bool isLocked() const { return locked_; }
+
+ private:
+  void assertOwnerThread() const;
+
+  uint8_t* page_ = nullptr;
+  size_t pageSize_ = 0;
+  size_t length_ = 0;
+  bool locked_ = false;
+  std::thread::id owner_;
+};
+
+}  // namespace esk

package/common/include/esk/SecureRandom.h

@@ -0,0 +1,24 @@
+// Copyright (c) 2026 expo-secure-keypad-jsi contributors. MIT License.
+#pragma once
+
+#include <array>
+#include <cstddef>
+#include <cstdint>
+
+namespace esk {
+
+// Thin wrapper over OpenSSL's CSPRNG (RAND_bytes). Throws EskError on failure
+// rather than returning weak/predictable bytes.
+namespace secure_random {
+
+// Fills buf with cryptographically secure random bytes. Throws on RAND failure.
+void bytes(uint8_t* buf, size_t len);
+
+// Returns a shuffled 0..9 layout using Fisher-Yates seeded from RAND_bytes.
+// The layout is generated natively and never leaves the native side except as
+// on-screen glyph positions, so JS never learns which coordinate maps to which
+// digit.
+std::array<uint8_t, 10> shuffledDigits();
+
+}  // namespace secure_random
+}  // namespace esk

package/common/include/esk/esk_c_api.h

@@ -0,0 +1,61 @@
+// Copyright (c) 2026 expo-secure-keypad-jsi contributors. MIT License.
+//
+// Flat C ABI over KeypadCore — the only surface the JNI and Objective-C++
+// bridges call. Every function is a no-throw boundary: internal failures
+// surface as error strings, a degraded return value, or are swallowed, never
+// as an unwinding exception. Strings are NUL-terminated UTF-8.
+#pragma once
+
+#include <stdint.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+typedef struct esk_keypad esk_keypad;
+
+// Unix seconds. Injected so the platform owns the clock.
+typedef int64_t (*esk_now_cb)(void* user);
+
+typedef struct {
+  int32_t min_length;  // clamped to [4,12] (digit) or [4,64] (full)
+  int32_t max_length;  // clamped to [4,12] (digit) or [4,64] (full)
+  int32_t keypad_type; // 0 = digit PIN pad, 1 = full QWERTY
+} esk_config;
+
+// NULL only on allocation failure.
+esk_keypad* esk_keypad_create(const esk_config* config, esk_now_cb now_cb,
+                              void* user);
+void esk_keypad_destroy(esk_keypad* kp);
+
+// NULL on success, else a static error-code string — do NOT free it.
+const char* esk_keypad_arm(esk_keypad* kp, const char* pem);
+
+// Key ops. Return the resulting entered-key count, or ESK_COUNT_ERROR (-1) if
+// the core refused the call — in practice only a cross-thread access, which is
+// a caller bug. Callers must not forward a negative count to JS as "0 entered":
+// the buffer was NOT modified and still holds the previous input.
+// esk_keypad_press takes a digit value 0..9; esk_keypad_press_key takes the
+// final ASCII character (printable, no space — the view resolves shift/layer
+// state first). Out-of-charset input is ignored, not an error.
+#define ESK_COUNT_ERROR (-1)
+int32_t esk_keypad_press(esk_keypad* kp, uint8_t digit);
+int32_t esk_keypad_press_key(esk_keypad* kp, uint8_t ascii_char);
+int32_t esk_keypad_backspace(esk_keypad* kp);
+void esk_keypad_clear(esk_keypad* kp);
+
+// Envelope JSON, caller frees with esk_free. NULL on failure, with a static
+// error-code string written to *err_out (do NOT free that one).
+char* esk_keypad_submit(esk_keypad* kp, const char** err_out);
+
+// out10 must hold 10 bytes and be pre-filled with the identity layout; it is
+// left untouched if the CSPRNG fails.
+void esk_keypad_shuffled_layout(esk_keypad* kp, uint8_t* out10);
+
+void esk_keypad_on_background(esk_keypad* kp);
+
+void esk_free(char* s);
+
+#ifdef __cplusplus
+}  // extern "C"
+#endif

package/common/src/Base64.cpp

@@ -0,0 +1,43 @@
+// Copyright (c) 2026 expo-secure-keypad-jsi contributors. MIT License.
+#include "esk/Base64.h"
+
+#include <openssl/evp.h>
+
+#include <vector>
+
+namespace esk {
+namespace base64 {
+
+std::string encode(const uint8_t* data, size_t len) {
+  if (len == 0) return std::string();
+  // EVP_EncodeBlock writes 4 chars per 3 bytes, plus a NUL.
+  const size_t outLen = 4 * ((len + 2) / 3);
+  std::string out(outLen, '\0');
+  const int written = EVP_EncodeBlock(reinterpret_cast<unsigned char*>(&out[0]),
+                                      data, static_cast<int>(len));
+  if (written < 0) return std::string();
+  out.resize(static_cast<size_t>(written));
+  return out;
+}
+
+bool decode(const std::string& in, std::string& out) {
+  if (in.empty()) {
+    out.clear();
+    return true;
+  }
+  std::vector<unsigned char> buf(3 * (in.size() / 4) + 3);
+  const int written = EVP_DecodeBlock(
+      buf.data(), reinterpret_cast<const unsigned char*>(in.data()),
+      static_cast<int>(in.size()));
+  if (written < 0) return false;
+  // EVP_DecodeBlock ignores '=' and always emits multiples of 3.
+  size_t realLen = static_cast<size_t>(written);
+  for (auto it = in.rbegin(); it != in.rend() && *it == '='; ++it) {
+    if (realLen > 0) --realLen;
+  }
+  out.assign(reinterpret_cast<char*>(buf.data()), realLen);
+  return true;
+}
+
+}  // namespace base64
+}  // namespace esk

package/common/src/Error.cpp

@@ -0,0 +1,21 @@
+// Copyright (c) 2026 expo-secure-keypad-jsi contributors. MIT License.
+#include "esk/Error.h"
+
+namespace esk {
+
+const char* errorCodeName(ErrorCode code) {
+  switch (code) {
+    case ErrorCode::KeyParse:       return "ERR_KEY_PARSE";
+    case ErrorCode::KeyNotRsa:      return "ERR_KEY_NOT_RSA";
+    case ErrorCode::WeakKey:        return "ERR_WEAK_KEY";
+    case ErrorCode::NotArmed:       return "ERR_NOT_ARMED";
+    case ErrorCode::Empty:          return "ERR_EMPTY";
+    case ErrorCode::TooShort:       return "ERR_TOO_SHORT";
+    case ErrorCode::Encrypt:        return "ERR_ENCRYPT";
+    case ErrorCode::Random:         return "ERR_RANDOM";
+    case ErrorCode::Internal:       return "ERR_INTERNAL";
+  }
+  return "ERR_UNKNOWN";
+}
+
+}  // namespace esk

package/common/src/KeypadCore.cpp

@@ -0,0 +1,105 @@
+// Copyright (c) 2026 expo-secure-keypad-jsi contributors. MIT License.
+#include "esk/KeypadCore.h"
+
+#include <algorithm>
+
+#include "esk/Error.h"
+#include "esk/PinEncryptor.h"
+#include "esk/SecureRandom.h"
+
+namespace esk {
+
+KeypadCore::KeypadCore(std::function<int64_t()> nowProvider, size_t minLength,
+                       size_t maxLength, KeypadType type)
+    : nowProvider_(std::move(nowProvider)), type_(type) {
+  const size_t cap =
+      type_ == KeypadType::Full ? kMaxSecretLength : kMaxPinLength;
+  minLength_ = std::clamp<size_t>(minLength, kMinPinLength, cap);
+  maxLength_ = std::clamp<size_t>(maxLength, kMinPinLength, cap);
+  if (minLength_ > maxLength_) minLength_ = maxLength_;
+}
+
+KeypadCore::~KeypadCore() = default;
+
+std::optional<std::string> KeypadCore::arm(const std::string& publicKeyPem) {
+  try {
+    key_ = PublicKey::parse(publicKeyPem, 2048, 8192);
+  } catch (const EskError& e) {
+    // A rejected key must not leave the previous session's secret behind.
+    key_.reset();
+    buffer_.clear();
+    state_ = KeypadState::Unarmed;
+    return std::string(e.codeName());
+  }
+  buffer_.clear();
+  state_ = KeypadState::Armed;
+  return std::nullopt;
+}
+
+size_t KeypadCore::pressDigit(uint8_t digit) {
+  if (digit > 9) return buffer_.length();
+  return pressKey(static_cast<uint8_t>('0' + digit));
+}
+
+size_t KeypadCore::pressKey(uint8_t asciiChar) {
+  if (state_ != KeypadState::Armed) {
+    return buffer_.length();
+  }
+  const bool allowed = type_ == KeypadType::Full
+                           ? isAllowedSecretByte(asciiChar)
+                           : (asciiChar >= '0' && asciiChar <= '9');
+  if (!allowed) {
+    return buffer_.length();
+  }
+  // Enforce the configured maxLength_ (SecureBuffer only enforces the hard
+  // kMaxSecretLength cap). Silently ignore presses past the configured length.
+  if (buffer_.length() >= maxLength_) {
+    return buffer_.length();
+  }
+  buffer_.append(asciiChar);
+  return buffer_.length();
+}
+
+size_t KeypadCore::backspace() {
+  if (state_ != KeypadState::Armed) return buffer_.length();
+  buffer_.pop();
+  return buffer_.length();
+}
+
+void KeypadCore::clearPin() { buffer_.clear(); }
+
+std::string KeypadCore::submit() {
+  if (state_ != KeypadState::Armed || !key_) {
+    throw EskError(ErrorCode::NotArmed, "keypad is not armed with a key");
+  }
+  const size_t len = buffer_.length();
+  if (len == 0) {
+    throw EskError(ErrorCode::Empty, "no digits entered");
+  }
+  if (len < minLength_) {
+    throw EskError(ErrorCode::TooShort, "PIN below configured minimum length");
+  }
+
+  const int64_t now = nowProvider_ ? nowProvider_() : 0;
+  std::string envelope;
+  try {
+    envelope = PinEncryptor::encrypt(buffer_, *key_, now);
+  } catch (...) {
+    buffer_.clear();
+    throw;
+  }
+  // Plaintext lifetime ends here.
+  buffer_.clear();
+  return envelope;
+}
+
+size_t KeypadCore::digitCount() const { return buffer_.length(); }
+
+std::array<uint8_t, 10> KeypadCore::shuffledLayout() const {
+  return secure_random::shuffledDigits();
+}
+
+// Unconditional: the entered value must not outlive the foreground.
+void KeypadCore::onHostBackground() { buffer_.clear(); }
+
+}  // namespace esk