HWID
====

LacePHP uses a Hardware ID (HWID) to generate a unique, reproducible token for each machine—without calling home. This token is used to tie AI licenses, feature flags or trial periods to a specific device.

Why HWID Matters
----------------
- **Offline licensing**  
  Prevent sharing of license keys across machines without needing an Internet lookup.  
- **Device-specific features**  
  Enable or disable functionality per machine (e.g. trial expiry).  
- **Audit & logging**  
  Tag logs or metrics by a non-guessable device identifier.

How It Works (Conceptually)
---------------------------
- The `lace_hwid($salt)` helper reads one of several machine identifiers (Linux machine-id, macOS UUID, Windows MachineGuid, or hostname+MAC).  
- It combines that ID with your “salt” and produces a signed, URL-safe base64 token.  
- A companion `lace_hwid_verify($token, $salt)` helper recomputes and validates the signature, returning **true** or **false**.

Using HWID in Your Code
-----------------------

1. **Generate the token**  
   Provide your secret salt (e.g. license key or shared secret):

   .. code-block:: php

      $salt  = config('auth.tokens.0');        // e.g. your license key
      $token = lace_hwid($salt);

      echo "Your device token is: {$token}\n";

2. **Verify the token**  
   When a user presents a token, confirm it matches the current machine:

   .. code-block:: php

      if (! lace_hwid_verify($token, $salt)) {
          exit("HWID mismatch. License not valid on this device.\n");
      }
      echo "HWID verified.\n";

Advanced Example: Locking a Trial Period
----------------------------------------
You can use HWID to implement a local trial that expires after a date:

.. code-block:: php

   // On first run, store token + expiry
   $token     = lace_hwid($salt);
   $expiresAt = (new \DateTime('+7 days'))->format('Y-m-d');
   file_put_contents('.trial', json_encode([
       'hwid'      => $token,
       'expiresAt' => $expiresAt
   ]));

   // On subsequent runs, verify
   $data = json_decode(file_get_contents('.trial'), true);
   if (! lace_hwid_verify($data['hwid'], $salt)) {
       exit("License token invalid for this machine.\n");
   }
   if (new \DateTime() > new \DateTime($data['expiresAt'])) {
       exit("Trial expired on {$data['expiresAt']}.\n");
   }

Best Practices
--------------
- **Treat the salt as secret**: never commit your license key or salt to public repositories.  
- **Use verification** on every startup if you’re gating features by device.  
- **Handle fallbacks** gracefully: if HWID cannot be retrieved (rare), fall back to a user prompt or offline mode.

.. warning::

   - **Privacy**: HWID may expose unique device information—use responsibly and inform users.  
   - **Portability**: moving a VM or re-imaging may change the HWID, invalidating the token.

|
|