migrate file-access tokens onto shared OneTimeToken model (hash-at-rest)

app/src/OneTimeToken.php

@@ -80,6 +80,38 @@ class OneTimeToken
         return json_decode($row['context'], true);
     }
 
+    /**
+     * Look up a token by purpose + value WITHOUT applying validity checks.
+     *
+     * Used by callers that need to attribute a redemption attempt (audit
+     * logging, resolving a bound resource) even when the token is expired
+     * or already used.
+     *
+     * @return array{id:int, context:mixed, is_valid:int, used_at:?string, expires_at:string}|null
+     */
+    public function lookup(string $purpose, string $token): ?array
+    {
+        $stmt = $this->pdo->prepare(
+            'SELECT id, context, is_valid, used_at, expires_at
+               FROM ' . self::TABLE . '
+              WHERE purpose = ? AND token_hash = ?
+              LIMIT 1'
+        );
+        $stmt->execute([$purpose, self::hash($token)]);
+        $row = $stmt->fetch();
+        if ($row === false) {
+            return null;
+        }
+
+        $row['id']       = (int) $row['id'];
+        $row['is_valid'] = (int) $row['is_valid'];
+        $row['context']  = ($row['context'] === null || $row['context'] === '')
+            ? null
+            : json_decode($row['context'], true);
+
+        return $row;
+    }
+
     /**
      * Look up a valid (unused, unexpired) token row by purpose + hash.
      */