fix(verify): validation security and API naming 🐛

NeaByteLab · NeaByteLab · commit 3e52943ef1c5 · 2026-03-02T13:43:37.000+07:00
- Reject non-integer secret in verify
- Rename getHash to generate in API, docs, and tests
- Enforce 0..1e10 range and strict equality in verify (fix 32-bit false accept)
- Update README and USAGE for default export and generate flow
- Update deno.json and package.json description and keywords
diff --git a/README.md b/README.md
@@ -37,26 +37,28 @@ deno add jsr:@neabyte/trustless-id
 
 ## Quick Start
 
-Create an instance with a **connector ID** (e.g. service URL or app identifier). Generate a one-time **hashId**, build a **requestId**, then decode to a numeric code or verify with a user secret.
+Use a **connector ID** (e.g. service URL or app identifier) on both sides. Generate a one-time **hashId**, create an **instance**, build a **requestId**, then decode to a numeric code or verify with a user secret.
 
 ```typescript
-import Trustless from '@neabyte/trustless-id'
+import trustless from '@neabyte/trustless-id'
 
 // Connector ID (same on both sides)
 const connectorId = 'trustless://auth/example.com:0.1.0?service=none'
-const instance = Trustless.create(connectorId)
 
 // One-time hashId per session
-const hashId = Trustless.getHash(connectorId)
+const hashId = trustless.generate(connectorId)
 
-// Request with 10s expiry window
+// Instance for connector (same on client and verifier)
+const instance = trustless.create(connectorId)
+
+// Build payload; send requestId to verifier (QR / link / form)
 const requestId = instance.request(hashId, 10)
 
-// Decode to code, or null if invalid/expired
+// Verifier decodes to get code
 const codeId = instance.decode(hashId, requestId)
 if (codeId !== null) {
   console.log('Code:', codeId)
-  // Verify user secret
+  // Check user secret
   console.log('Verify:', instance.verify(requestId, codeId))
 }
 ```
diff --git a/USAGE.md b/USAGE.md
@@ -16,19 +16,21 @@ API, flow, options — request, decode, verify time-bound IDs.
 
 ## Quick Start
 
-**Flow:** `connectorId` → instance → `hashId` → request → decode → verify.
+**Flow:** `connectorId` → hashId → instance → request → decode → verify.
 
 ```typescript
-import Trustless from '@neabyte/trustless-id'
+import trustless from '@neabyte/trustless-id'
 
 // Connector ID (same on both sides)
 const connectorId = 'trustless://auth/example.com:0.1.0?service=none'
-const instance = Trustless.create(connectorId)
 
 // One-time hashId per session
-const hashId = Trustless.getHash(connectorId)
+const hashId = trustless.generate(connectorId)
 
-// Request with 10s expiry window
+// Instance for connector (same on client and verifier)
+const instance = trustless.create(connectorId)
+
+// Request with 10s expiry window; send requestId to verifier (QR / link / form)
 const requestId = instance.request(hashId, 10)
 
 // Decode to code, or null if invalid/expired
@@ -41,66 +43,67 @@ if (codeId !== null) {
 
 ## Flow Overview
 
-1. **Connector** — Both client and verifier use the same `connectorId` (e.g. service URL). Each creates `Trustless.create(connectorId)`.
-2. **Hash** — Client calls `Trustless.getHash(connectorId)` once per session; returns a 197-char hex `hashId` (unique per call).
-3. **Request** — Client calls `instance.request(hashId, expireTime?)` to get `requestId` (encoded payload with time slot and window). Send `requestId` (e.g. QR, link, form).
-4. **Decode** — Verifier has `hashId` (e.g. stored or passed with the request). Verifier calls `instance.decode(hashId, requestId)` to get numeric `codeId`, or `null` if invalid/expired.
-5. **Verify** — User enters the code (or it’s shown). Verifier calls `instance.verify(requestId, secret)` with that value; returns `true` when not expired and code matches.
+1. **Connector** — Both client and verifier use the same `connectorId` (e.g. service URL).
+2. **Hash** — Client calls `trustless.generate(connectorId)` once per session; returns a 197-char hex `hashId` (unique per call). This is the session identifier.
+3. **Instance** — Both sides call `trustless.create(connectorId)` to get an instance bound to that connector.
+4. **Request** — Client calls `instance.request(hashId, expireTime?)` to get `requestId`. Send `requestId` and `hashId` to the verifier (e.g. QR, link, form).
+5. **Decode** — Verifier calls `instance.decode(hashId, requestId)` to get numeric `codeId`, or `null` if invalid/expired. Verifier must use the same `hashId` received from the client.
+6. **Verify** — User enters the code (or it’s shown). Verifier calls `instance.verify(requestId, secret)`; returns `true` when not expired and code matches.
 
 ## Methods Overview
 
 | Method                                                                       | Type     | Returns          | Description                                       |
 | :--------------------------------------------------------------------------- | :------- | :--------------- | :------------------------------------------------ |
-| [`Trustless.create(connectorId)`](#trustlesscreateconnectorid)               | static   | `Trustless`      | Factory: new instance bound to connector.         |
-| [`Trustless.getHash(connectorId)`](#trustlessgethashconnectorid)             | static   | `HashId`         | One-time 197-char hex hash.                       |
+| [`trustless.create(connectorId)`](#trustlesscreateconnectorid)               | static   | instance         | Factory: new instance bound to connector.         |
+| [`trustless.generate(connectorId)`](#trustlessgenerateconnectorid)           | static   | `HashId`         | One-time 197-char hex hash.                       |
 | [`instance.request(hashId, expireTime?)`](#instancerequesthashid-expiretime) | instance | `RequestId`      | Encoded payload string or `''` if hashId invalid. |
 | [`instance.decode(hashId, requestId)`](#instancedecodehashid-requestid)      | instance | `CodeId \| null` | Numeric code when valid and not expired.          |
 | [`instance.verify(requestId, secret)`](#instanceverifyrequestid-secret)      | instance | `boolean`        | True when not expired and secret matches code.    |
 
 ## ConnectorId and HashId
 
 - **ConnectorId** — Any non-secret string that identifies the connector (e.g. `trustless://auth/example.com:0.1.0?service=none`). Trimmed before hashing. Same value on both sides yields the same encryption key.
-- **HashId** — 197 lowercase hex chars from `Trustless.getHash(connectorId)`. Includes timestamp and random nonce; different on every call. Must be passed to `request` and (on verifier side) to `decode` for the same session.
+- **HashId** — 197 lowercase hex chars from `trustless.generate(connectorId)`. Includes timestamp and random nonce; different on every call. Client must pass `hashId` together with `requestId` to the verifier so the verifier can call `decode(hashId, requestId)`.
 
-```typescript
-const hashId = Trustless.getHash(connectorId)
-// hashId.length === 197, /^[0-9a-f]{197}$/.test(hashId) === true
-```
+  ```typescript
+  const hashId = trustless.generate(connectorId)
+  // hashId.length === 197, /^[0-9a-f]{197}$/.test(hashId) === true
+  ```
 
 ## Request and Expiry
 
 - **request(hashId, expireTime?)** — Validates `hashId` (197 hex chars), then encodes `hashId` + current time slot + window. Returns fixed-length `RequestId` or `''` if `hashId` invalid.
 - **expireTime** — Window in seconds (1–60). Default 10. Clamped via `Cipher.clampWindow`. Same `hashId` and same window in the same time slot yields the same `requestId` and same `codeId`.
 
-```typescript
-const requestId = instance.request(hashId, 10)
-const requestIdLong = instance.request(hashId, 60)
-// requestId length: 6 (slot) + 2 (window) + 197 (hashId) = 205
-```
+  ```typescript
+  const requestId = instance.request(hashId, 10)
+  const requestIdLong = instance.request(hashId, 60)
+  // requestId length: 6 (slot) + 2 (window) + 197 (hashId) = 205
+  ```
 
 ## Decode and Verify
 
 - **decode(hashId, requestId)** — Decodes with instance key; checks expiry; ensures payload `hashId` matches argument; returns derived numeric code or `null`. Code is in range `0`–`1e10`.
 - **verify(requestId, secret)** — Decodes, checks expiry, derives expected code, compares to `secret`. `secret` can be number or string (digits only); returns `true` when match and not expired.
 
-```typescript
-const codeId = instance.decode(hashId, requestId)
-if (codeId !== null) {
-  instance.verify(requestId, codeId) === true
-  instance.verify(requestId, String(codeId)) === true
-}
-```
+  ```typescript
+  const codeId = instance.decode(hashId, requestId)
+  if (codeId !== null) {
+    instance.verify(requestId, codeId) === true
+    instance.verify(requestId, String(codeId)) === true
+  }
+  ```
 
 ## API Reference
 
-### Trustless.create(connectorId)
+### trustless.create(connectorId)
 
 Create an instance bound to the given connector. The instance key is a hash of the trimmed `connectorId`.
 
 - `connectorId` `<ConnectorId>`: Caller identifier (string, trimmed).
-- Returns: `<Trustless>` New instance.
+- Returns: New instance (use for `request`, `decode`, `verify`).
 
-### Trustless.getHash(connectorId)
+### trustless.generate(connectorId)
 
 Generate a one-time 197-char hex hash. Uses connectorId + timestamp + random nonce. Call once per session; each call returns a different value.
 
@@ -111,7 +114,7 @@ Generate a one-time 197-char hex hash. Uses connectorId + timestamp + random non
 
 Build the encoded request payload for the given hash and optional expiry window.
 
-- `hashId` `<HashId>`: 197-char hex from `getHash`.
+- `hashId` `<HashId>`: 197-char hex from `generate`.
 - `expireTime` `<ExpireTime | undefined>`: Window in seconds (1–60). Default 10.
 - Returns: `<RequestId>` Encoded string of length 205, or `''` if `hashId` invalid.
 
@@ -136,7 +139,7 @@ Check that the user-provided secret matches the derived code and the payload is
 Types are exported for TypeScript: `import type { CodeId, ConnectorId, DecodedPayload, ExpireTime, HashId, RequestId, VerifySecret } from '@neabyte/trustless-id'`.
 
 - **ConnectorId:** `<string>` — Caller identifier.
-- **HashId:** `<string>` — 197-char hex from `getHash`.
+- **HashId:** `<string>` — 197-char hex from `generate`.
 - **RequestId:** `<string>` — Encoded payload from `request`.
 - **CodeId:** `<number>` — Numeric code from `decode` (0–1e10).
 - **ExpireTime:** `<number>` — Window in seconds (1–60).
diff --git a/deno.json b/deno.json
@@ -1,6 +1,6 @@
 {
   "name": "@neabyte/trustless-id",
-  "description": "Trustless ID",
+  "description": "Time-bound anonymous ID: request, decode, verify. No server",
   "version": "0.1.0",
   "type": "module",
   "license": "MIT",
diff --git a/package.json b/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@neabyte/trustless-id",
   "version": "0.1.0",
-  "description": "Trustless ID",
+  "description": "Time-bound anonymous ID: request, decode, verify. No server",
   "type": "module",
   "main": "dist/index.cjs",
   "module": "dist/index.mjs",
@@ -19,8 +19,25 @@
     "prepublishOnly": "rm -rf dist && npm run build"
   },
   "keywords": [
+    "anonymous-id",
+    "client-side",
+    "connector",
+    "deno",
+    "esm",
+    "handshake",
+    "javascript",
+    "library",
+    "no-server",
+    "nodejs",
+    "one-time-code",
+    "pairing",
+    "session-id",
+    "time-bound",
     "trustless",
-    "anonymous-id"
+    "typescript",
+    "verification",
+    "verification-code",
+    "zero-dependency"
   ],
   "dependencies": {},
   "devDependencies": {
diff --git a/src/Types.ts b/src/Types.ts
@@ -1,11 +1,15 @@
 /** Connector identifier from caller. */
 export type ConnectorId = string
-/** 197-char hex hash from getHash. */
+
+/** 197-char hex hash from generate. */
 export type HashId = string
+
 /** Encoded payload string from request. */
 export type RequestId = string
+
 /** Numeric code from decode for verification. */
 export type CodeId = number
+
 /** Expiry window in seconds (1–60). */
 export type ExpireTime = number
 
diff --git a/src/index.ts b/src/index.ts
@@ -34,7 +34,7 @@ export default class Trustless {
    * @param connectorId - Caller identifier
    * @returns 197-char hex HashId
    */
-  static getHash(connectorId: Types.ConnectorId): Types.HashId {
+  static generate(connectorId: Types.ConnectorId): Types.HashId {
     const nonce = String(Date.now()) + String(Math.random())
     return Cipher.generateHash(String(connectorId).trim() + nonce)
   }
@@ -63,7 +63,7 @@ export default class Trustless {
   /**
    * Build requestId for hashId and optional window.
    * @description Validates hashId then encodes with current slot and window.
-   * @param hashId - 197-char hex from getHash
+   * @param hashId - 197-char hex from generate
    * @param expireTime - Optional window seconds (default 10)
    * @returns RequestId string or empty when hashId invalid
    */
@@ -98,10 +98,13 @@ export default class Trustless {
     const actualCode = typeof secret === 'number'
       ? secret
       : parseInt(String(secret).replace(/\D/g, ''), 10)
-    if (Number.isNaN(actualCode)) {
+    if (Number.isNaN(actualCode) || !Number.isInteger(actualCode)) {
       return false
     }
-    return expectedCode >>> 0 === actualCode >>> 0
+    if (actualCode < 0 || actualCode > 1e10) {
+      return false
+    }
+    return expectedCode === actualCode
   }
 }
 
diff --git a/tests/EdgeCases.test.ts b/tests/EdgeCases.test.ts
@@ -18,7 +18,7 @@ Deno.test('EdgeCases - connectorId with whitespace is trimmed', () => {
   const connectorId = makeConnectorId('example.com')
   const withSpaces = '  ' + connectorId + '  '
   const instance = Trustless.create(withSpaces)
-  const hashId = Trustless.getHash(connectorId)
+  const hashId = Trustless.generate(connectorId)
   const requestId = instance.request(hashId, 10)
   const codeId = instance.decode(hashId, requestId)
   assertEquals(codeId !== null, true)
@@ -28,7 +28,7 @@ Deno.test('EdgeCases - connectorId with whitespace is trimmed', () => {
 Deno.test('EdgeCases - decode with empty hashId string still validates by hashId match', () => {
   const connectorId = makeConnectorId('example.com')
   const instance = Trustless.create(connectorId)
-  const hashId = Trustless.getHash(connectorId)
+  const hashId = Trustless.generate(connectorId)
   const requestId = instance.request(hashId, 10)
   const codeId = instance.decode('', requestId)
   assertEquals(codeId, null)
@@ -49,7 +49,7 @@ Deno.test('EdgeCases - isExpired with invalid requestId returns true', () => {
 Deno.test('EdgeCases - request clamps expireTime to valid range', () => {
   const connectorId = makeConnectorId('example.com')
   const instance = Trustless.create(connectorId)
-  const hashId = Trustless.getHash(connectorId)
+  const hashId = Trustless.generate(connectorId)
   const requestIdZero = instance.request(hashId, 0)
   const requestIdHuge = instance.request(hashId, 999)
   assert(requestIdZero.length > 0)
@@ -80,7 +80,7 @@ Deno.test(
   () => {
     const connectorId = makeConnectorId('example.com')
     const instance = Trustless.create(connectorId)
-    const hashId = Trustless.getHash(connectorId)
+    const hashId = Trustless.generate(connectorId)
     const requestId = instance.request(hashId, Number.NaN)
     assertEquals(requestId.length, 205)
     const codeId = instance.decode(hashId, requestId)
@@ -94,7 +94,7 @@ Deno.test(
   () => {
     const connectorId = makeConnectorId('example.com')
     const instance = Trustless.create(connectorId)
-    const hashId = Trustless.getHash(connectorId)
+    const hashId = Trustless.generate(connectorId)
     const requestId = instance.request(hashId, -5)
     assertEquals(requestId.length, 205)
     const codeId = instance.decode(hashId, requestId)
@@ -105,15 +105,15 @@ Deno.test(
 Deno.test('EdgeCases - verify NaN secret returns false', () => {
   const connectorId = makeConnectorId('example.com')
   const instance = Trustless.create(connectorId)
-  const hashId = Trustless.getHash(connectorId)
+  const hashId = Trustless.generate(connectorId)
   const requestId = instance.request(hashId, 10)
   assertEquals(instance.verify(requestId, Number.NaN), false)
 })
 
 Deno.test('EdgeCases - verify with string leading zeros strips and validates', () => {
   const connectorId = makeConnectorId('example.com')
   const instance = Trustless.create(connectorId)
-  const hashId = Trustless.getHash(connectorId)
+  const hashId = Trustless.generate(connectorId)
   const requestId = instance.request(hashId, 10)
   const codeId = instance.decode(hashId, requestId)
   assert(codeId !== null)
@@ -124,7 +124,7 @@ Deno.test('EdgeCases - verify with string leading zeros strips and validates', (
 Deno.test('EdgeCases - verify with string non-numeric secret returns false', () => {
   const connectorId = makeConnectorId('example.com')
   const instance = Trustless.create(connectorId)
-  const hashId = Trustless.getHash(connectorId)
+  const hashId = Trustless.generate(connectorId)
   const requestId = instance.request(hashId, 10)
   assertEquals(instance.verify(requestId, 'no-digits'), false)
   assertEquals(instance.verify(requestId, ''), false)
@@ -133,7 +133,7 @@ Deno.test('EdgeCases - verify with string non-numeric secret returns false', ()
 Deno.test('EdgeCases - verify with string secret strips non-digits and validates', () => {
   const connectorId = makeConnectorId('example.com')
   const instance = Trustless.create(connectorId)
-  const hashId = Trustless.getHash(connectorId)
+  const hashId = Trustless.generate(connectorId)
   const requestId = instance.request(hashId, 10)
   const codeId = instance.decode(hashId, requestId)
   assert(codeId !== null)
diff --git a/tests/Expiration.test.ts b/tests/Expiration.test.ts
diff --git a/tests/Security.test.ts b/tests/Security.test.ts
diff --git a/tests/Trustless.test.ts b/tests/Trustless.test.ts

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "@neabyte/trustless-id",`
`3`		`- "description": "Trustless ID",`
	`3`	`+ "description": "Time-bound anonymous ID: request, decode, verify. No server",`
`4`	`4`	`"version": "0.1.0",`
`5`	`5`	`"type": "module",`
`6`	`6`	`"license": "MIT",`